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	No	null	Context a chat is bound to when it has not picked one
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

The setup wizard fills this in for you, by having you message the bot and type back the code it replies with. To add a second account by hand, send /start to @userinfobot to find its numeric 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)

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) and an out-of-band opencode auth login. The CLI is downloaded on first use. 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	—	"libvirt" (Linux), "lima" (macOS), or "hcs" (Windows)
enabled	bool	No	true	Enable or disable the sandbox
computer_use	bool	No	false	Enable GUI interaction with a headless desktop
memory	int	No	2048	Memory ceiling in MB (Libvirt, Lima, and HCS backends)
cpus	int	No	2	Number of vCPUs (Libvirt, Lima, and HCS backends). HCS rejects a count above the host’s logical processor count
disk_size	int	No	20	Disk size in GB for the qcow2 overlay (Libvirt, Lima) or each dynamic VHDX volume (HCS)
base_image	string	No	null	Path to a base image you supply — qcow2 for Libvirt, VHDX for HCS. Both backends download one when unset
provision	string	No	null	Shell script to run on first boot (Libvirt, Lima, and HCS backends)

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 a chat is bound to when it has not picked one. Optional — when omitted, a chat is asked to choose a project instead of being bound to one. When set it must match a key in contexts.

contexts may itself be empty, which is what a fresh install looks like before its first project is added.

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: libvirt
      memory: 4096
      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