Configuration Reference

Full reference for config.yaml. The default location depends on your platform:

Linux

~/.config/openshrimp/config.yaml

macOS

~/Library/Application Support/openshrimp/config.yaml

You can also edit the configuration from the web app at /config when the bot is running.

For a guided walkthrough, see Configuration.

Top-level fields

Field	Type	Required	Default	Description
telegram	object	Yes	—	Telegram bot settings
allowed_users	list of int	Yes	—	Telegram user IDs allowed to use the bot
contexts	map	Yes	—	Named project contexts
default_context	string	Yes	—	Context to use when none is selected
backend	string	No	claude_sdk	Agent runtime: claude_sdk or opencode. Distinct from sandbox.backend (the sandbox type). See Agent Backends
review	object	No	—	Mini App HTTP server settings
instance_name	string	No	null	Display name for this instance (shown in status)

telegram

Field	Type	Required	Default	Description
token	string	Yes	—	Bot token from @BotFather

telegram:
  token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

allowed_users

A non-empty list of Telegram user IDs (integers). Messages from users not in this list are silently ignored.

allowed_users:
  - 123456789
  - 987654321

Tip

Send /start to @userinfobot to find your Telegram user ID.

contexts

A map of context name to context configuration. At least one context is required.

contexts:
  myproject:
    directory: /home/you/Documents/myproject
    description: "My main project"
    allowed_tools:
      - LSP
      - AskUserQuestion

Context fields

Field	Type	Required	Default	Description
directory	string	Yes	—	Absolute path to the project directory
description	string	Yes	—	Short description shown in the context list
allowed_tools	list of string	Yes	—	Tools auto-approved without prompting
model	string	No	null	Model override. Short names: sonnet, opus, haiku, or a full model ID
additional_directories	list of string	No	[]	Extra directories the agent can access
default_for_chats	list of int	No	[]	Chat IDs where this context is auto-selected on first use
locked_for_chats	list of int	No	[]	Chat IDs locked to this context (users cannot switch)
backend	string	No	inherits top-level	Per-context override of the agent runtime (claude_sdk or opencode). Inherits the top-level backend when omitted. This is the agent runtime — distinct from sandbox.backend (the sandbox type)
sandbox	object	No	null	Sandbox configuration (see below)
container	object or bool	No	null	Legacy Docker sandbox config (use sandbox instead)

Caution

You cannot specify both container and sandbox on the same context. The container key is a backwards-compatible alias for sandbox with backend: docker.

Note

The context-level backend (agent runtime) is unrelated to sandbox.backend (sandbox type). The opencode backend has extra preconditions: provider-qualified models (provider/model), out-of-band opencode auth login, and a discoverable opencode binary. See Agent Backends.

allowed_tools

Tools listed here are passed to the Claude CLI as --allowedTools and are always approved without prompting. Glob patterns are supported:

allowed_tools:
  - LSP
  - AskUserQuestion
  - "Bash(git *)"        # allow all git commands
  - "Bash(npm test)"     # allow npm test specifically

Tools not in this list go through OpenShrimp’s path-scoped approval:

• Read, Glob, Grep — auto-approved when the target path is within the context directory (or additional_directories)
• Edit, Write — always require manual approval via Telegram inline keyboard, with an option to “Accept all edits” for the session
• Bash — requires approval; you can approve by command prefix (e.g. “Accept all git”) or blanket-approve the entire tool
• Paths outside the context directory always require manual approval

Caution

Adding Read, Write, Edit, Glob, or Grep to allowed_tools bypasses path checking entirely — the agent can access any file the process can read.

additional_directories

Extra directories passed to the SDK as --add-dir. Path-scoped auto-approval (Read, Glob, Grep) extends to these directories.

additional_directories:
  - /home/you/Documents/shared-lib
  - /home/you/Documents/api-service

default_for_chats and locked_for_chats

Control which context is used in group chats:

contexts:
  frontend:
    # ...
    default_for_chats:
      - -1001234567890    # this group starts with the frontend context
    locked_for_chats:
      - -1009876543210    # this group can only use the frontend context

• default_for_chats — sets the initial context for a group chat. Users can still switch with /context.
• locked_for_chats — locks the group chat to this context. The /context command is disabled.

Chat IDs for groups are negative numbers. You can find them from the bot’s logs or via /status in the group.

contexts.<name>.sandbox

Run the Claude CLI inside an isolated environment. When a sandbox is enabled, all Bash commands and path-scoped tools are auto-approved since the sandbox provides the safety boundary.

Field	Type	Required	Default	Description
backend	string	Yes	—	"docker", "libvirt", or "lima"
enabled	bool	No	true	Enable or disable the sandbox
docker_in_docker	bool	No	false	Enable rootless Docker inside the container (Docker backend only)
dockerfile	string	No	null	Path to a custom Dockerfile (Docker backend only)
computer_use	bool	No	false	Enable GUI interaction with a headless desktop
memory	int	No	2048	Memory ceiling in MB (Libvirt and Lima backends)
cpus	int	No	2	Number of vCPUs (Libvirt and Lima backends)
disk_size	int	No	20	Disk size in GB for qcow2 overlay (Libvirt and Lima backends)
base_image	string	No	null	Path to base qcow2/cloud image (Libvirt backend only)
provision	string	No	null	Shell script to run on first boot (Libvirt and Lima backends)

Docker backend

sandbox:
  backend: docker
  docker_in_docker: true
  dockerfile: /path/to/Dockerfile.claude
  computer_use: true

• The project directory is bind-mounted into the container
• Session storage is isolated under ~/.config/openshrimp/containers/<context>/
• Container runs as host uid/gid
• Custom Dockerfiles should FROM openshrimp-claude:latest; images are tagged openshrimp-claude:<context-name> and built lazily
• docker_in_docker: true adds --cap-add SYS_ADMIN (reduced isolation)

See the Docker Sandbox guide for detailed setup instructions.

Libvirt backend

sandbox:
  backend: libvirt
  memory: 4096
  cpus: 4
  disk_size: 40
  base_image: /var/lib/libvirt/images/ubuntu-24.04-minimal.qcow2
  provision: |
    apt-get update && apt-get install -y git nodejs npm

Requires the libvirt-python optional dependency (uv pip install libvirt-python).

See the VM Sandbox guide for detailed setup instructions.

Lima backend

sandbox:
  backend: lima
  memory: 4096
  cpus: 4
  disk_size: 40
  provision: |
    apt-get update && apt-get install -y git nodejs npm

macOS only. Uses Apple Virtualization.framework via Lima. OpenShrimp downloads limactl automatically on first use — no manual installation needed.

See the Lima Sandbox guide for detailed setup instructions.

Computer use

When computer_use: true is set, the sandbox runs a headless Wayland desktop (labwc compositor, 1280x720) with Chromium and a foot terminal. Claude interacts via MCP tools: computer_screenshot, computer_click, computer_type, computer_key, computer_scroll, and computer_toplevel.

A VNC server is exposed for live viewing — use /vnc to open the noVNC viewer.

See the Computer Use guide for more details.

default_context

The context used when no context has been selected for a chat. Must match a key in contexts.

default_context: myproject

review

Optional HTTP server configuration for Mini Apps (Review, Terminal, VNC, Markdown preview).

Field	Type	Required	Default	Description
host	string	No	"127.0.0.1"	HTTP server bind address
port	int	No	8080	HTTP server port
public_url	string	No	null	Public URL for Mini Apps (when behind a reverse proxy)
tunnel	string	No	null	"cloudflared" to auto-start a public tunnel

review:
  host: "127.0.0.1"
  port: 8080
  tunnel: cloudflared

• public_url — set this when you have your own reverse proxy or domain pointing to the HTTP server
• tunnel: cloudflared — auto-starts a Cloudflare quick tunnel (free, no account needed). Downloads cloudflared automatically if not installed. Ignored if public_url is already set.

Note

Mini Apps require either public_url or tunnel to be configured. Without a public URL, Telegram cannot load the web apps.

instance_name

Optional display name for this OpenShrimp instance. Shown in /status output. Useful if you run multiple instances.

instance_name: "home-server"

Complete example

telegram:
  token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

allowed_users:
  - 123456789

contexts:
  default:
    directory: /home/you/Documents/your-project
    description: "Default context"
    allowed_tools:
      - LSP
      - AskUserQuestion

  webapp:
    directory: /home/you/Documents/webapp
    description: "Web application"
    model: sonnet
    allowed_tools:
      - LSP
      - AskUserQuestion
      - "Bash(npm *)"
    additional_directories:
      - /home/you/Documents/shared-components
    sandbox:
      backend: docker
      docker_in_docker: true
      computer_use: true

  infrastructure:
    directory: /home/you/Documents/infra
    description: "Infrastructure (locked to ops group)"
    allowed_tools:
      - LSP
      - AskUserQuestion
    locked_for_chats:
      - -1001234567890

default_context: default

review:
  port: 8080
  tunnel: cloudflared