Cấu hình¶

Repository cung cấp một starter file có thể copy: .env.example. Docker Compose tự động đọc .env được tạo, và runtime khác có thể dùng cùng environment variables LOCAL_SHELL_MCP_. YAML vẫn là optional advanced input cho binary/source deployments; tạo file rõ ràng và chọn bằng LOCAL_SHELL_MCP_CONFIG hoặc --config. Environment variables override YAML values, vì vậy tránh định nghĩa cùng setting ở cả hai nơi trừ khi override là chủ ý. YAML keys dùng các field names bên dưới.

Độ ưu tiên¶

Built-in defaults từ Settings.
YAML config được chọn bởi LOCAL_SHELL_MCP_CONFIG hoặc --config.
Environment variables với prefix LOCAL_SHELL_MCP_.
CLI flags như --mode, --config, --remote, --no-remote, đặt environment values tương ứng trước khi settings load.

Minimal public configuration¶

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-long-random-secret

Cho local-only testing, auth_bypass_localhost được bật mặc định. Không expose unauthenticated full MCP tools trên public network.

Settings reference¶

Server và workspace¶

YAML key	Environment variable	Default	Ghi chú
`host`	`LOCAL_SHELL_MCP_HOST`	`'0.0.0.0'`
`port`	`LOCAL_SHELL_MCP_PORT`	`8765`
`forwarded_allow_ips`	`LOCAL_SHELL_MCP_FORWARDED_ALLOW_IPS`	`'127.0.0.1'`	Comma-separated trusted proxy IPs cho Uvicorn forwarded-header handling. Chỉ dùng `*` khi direct ingress đã bị giới hạn.
`mode`	`LOCAL_SHELL_MCP_MODE`	`'mcp'`	`mcp`, `http`, `stdio`, hoặc giá trị reserved `both`.
`workspace_root`	`LOCAL_SHELL_MCP_WORKSPACE_ROOT`	`PosixPath('/workspace')`
`state_dir`	`LOCAL_SHELL_MCP_STATE_DIR`	`PosixPath('/workspace/.local-shell-mcp')`
`audit_log_path`	`LOCAL_SHELL_MCP_AUDIT_LOG_PATH`	`PosixPath('/workspace/.local-shell-mcp/audit.jsonl')`
`agent_config_dir`	`LOCAL_SHELL_MCP_AGENT_CONFIG_DIR`	`PosixPath('/workspace/.local-shell-mcp/agent_config')`
`allow_full_container`	`LOCAL_SHELL_MCP_ALLOW_FULL_CONTAINER`	`False`	Tắt workspace/path restrictions khi true; chỉ dùng trong disposable boundaries.
`disable_local`	`LOCAL_SHELL_MCP_DISABLE_LOCAL`	`False`	Tắt controller host làm target thực thi shell/file/browser. Remote workers và control-plane services vẫn hoạt động.
`stateless_controller`	`LOCAL_SHELL_MCP_STATELESS_CONTROLLER`	`False`	Làm controller phù hợp instance ephemeral/serverless: imply `disable_local`, tắt local file links/wallpaper caching và default `state_backend=memory`. Với `auth_mode=oauth`, cấu hình rõ `oauth_jwt_secret` mạnh.
`state_backend`	`LOCAL_SHELL_MCP_STATE_BACKEND`	`'file'`	`file`, `memory`, hoặc `redis`. Dùng Redis khi serverless controller state phải tồn tại qua cold starts.
`state_backend_url`	`LOCAL_SHELL_MCP_STATE_BACKEND_URL`	`None`	Redis connection URL khi `state_backend=redis`. Redacted trong diagnostics.
`state_backend_prefix`	`LOCAL_SHELL_MCP_STATE_BACKEND_PREFIX`	`'local-shell-mcp'`	Namespace cho memory/Redis control-plane state.

Giới hạn¶

YAML key	Environment variable	Default	Ghi chú
`default_timeout_s`	`LOCAL_SHELL_MCP_DEFAULT_TIMEOUT_S`	`60`
`max_timeout_s`	`LOCAL_SHELL_MCP_MAX_TIMEOUT_S`	`3600`
`max_output_bytes`	`LOCAL_SHELL_MCP_MAX_OUTPUT_BYTES`	`200000`
`max_file_read_bytes`	`LOCAL_SHELL_MCP_MAX_FILE_READ_BYTES`	`512000`
`max_file_write_bytes`	`LOCAL_SHELL_MCP_MAX_FILE_WRITE_BYTES`	`5000000`
`max_grep_results`	`LOCAL_SHELL_MCP_MAX_GREP_RESULTS`	`200`
`max_directory_entries`	`LOCAL_SHELL_MCP_MAX_DIRECTORY_ENTRIES`	`5000`
`max_glob_results`	`LOCAL_SHELL_MCP_MAX_GLOB_RESULTS`	`5000`
`max_tree_entries`	`LOCAL_SHELL_MCP_MAX_TREE_ENTRIES`	`5000`
`max_skills`	`LOCAL_SHELL_MCP_MAX_SKILLS`	`256`	Số Skill directories tối đa trả về bởi một registry scan.
`max_skill_related_files`	`LOCAL_SHELL_MCP_MAX_SKILL_RELATED_FILES`	`1000`	Số related files tối đa trả về cho một Skill.
`max_skill_scan_entries`	`LOCAL_SHELL_MCP_MAX_SKILL_SCAN_ENTRIES`	`5000`	Số filesystem entries tối đa được kiểm tra bởi một `skill_list` registry scan hoặc direct Skill load.
`max_skill_path_bytes`	`LOCAL_SHELL_MCP_MAX_SKILL_PATH_BYTES`	`200000`	Số UTF-8 bytes tối đa dùng cho returned related-file paths.
`max_read_many_files`	`LOCAL_SHELL_MCP_MAX_READ_MANY_FILES`	`100`
`max_read_many_total_bytes`	`LOCAL_SHELL_MCP_MAX_READ_MANY_TOTAL_BYTES`	`5000000`
`max_http_request_bytes`	`LOCAL_SHELL_MCP_MAX_HTTP_REQUEST_BYTES`	`16000000`	Kích thước tối đa buffered HTTP request body trên các endpoint MCP, REST, OAuth, UI và remote-worker.
`max_job_log_bytes`	`LOCAL_SHELL_MCP_MAX_JOB_LOG_BYTES`	`10000000`	Số output bytes tối đa giữ cho mỗi long-running job attempt.
`max_jobs`	`LOCAL_SHELL_MCP_MAX_JOBS`	`1000`	Số long-running job records tối đa giữ lại; active jobs không bao giờ pruned.
`max_audit_tail_bytes`	`LOCAL_SHELL_MCP_MAX_AUDIT_TAIL_BYTES`	`1000000`
`max_audit_log_bytes`	`LOCAL_SHELL_MCP_MAX_AUDIT_LOG_BYTES`	`20000000`
`max_audit_archive_bytes`	`LOCAL_SHELL_MCP_MAX_AUDIT_ARCHIVE_BYTES`	`512000000`
`max_tmp_files`	`LOCAL_SHELL_MCP_MAX_TMP_FILES`	`500`
`max_tmp_bytes`	`LOCAL_SHELL_MCP_MAX_TMP_BYTES`	`50000000`
`max_transfer_archive_entries`	`LOCAL_SHELL_MCP_MAX_TRANSFER_ARCHIVE_ENTRIES`	`100000`	Số entries tối đa chấp nhận khi unpack transferred directory archive.
`max_transfer_unpacked_bytes`	`LOCAL_SHELL_MCP_MAX_TRANSFER_UNPACKED_BYTES`	`10000000000`	Số declared expanded bytes tối đa chấp nhận cho transferred directory archive.
`max_concurrent_commands`	`LOCAL_SHELL_MCP_MAX_CONCURRENT_COMMANDS`	`4`
`max_tmux_sessions`	`LOCAL_SHELL_MCP_MAX_TMUX_SESSIONS`	`16`	Số persistent shell sessions tối đa trên các backend tmux, ConPTY và native fallback.

File links¶

YAML key	Environment variable	Default	Ghi chú
`file_download_enabled`	`LOCAL_SHELL_MCP_FILE_DOWNLOAD_ENABLED`	`True`
`file_download_default_ttl_s`	`LOCAL_SHELL_MCP_FILE_DOWNLOAD_DEFAULT_TTL_S`	`3600`
`file_download_max_ttl_s`	`LOCAL_SHELL_MCP_FILE_DOWNLOAD_MAX_TTL_S`	`604800`
`file_download_default_max_downloads`	`LOCAL_SHELL_MCP_FILE_DOWNLOAD_DEFAULT_MAX_DOWNLOADS`	`0`	`0` nghĩa là không có default download-count limit.
`file_download_max_file_bytes`	`LOCAL_SHELL_MCP_FILE_DOWNLOAD_MAX_FILE_BYTES`	`0`	`0` nghĩa là không có configured file-size cap cho download links.

Human interface¶

YAML key	Environment variable	Default	Ghi chú
`logical_sessions_enabled`	`LOCAL_SHELL_MCP_LOGICAL_SESSIONS_ENABLED`	`True`	Công khai `session_manage` và `plan_manage`, đồng thời thêm đối số `logical_session_id` bắt buộc nhưng cho phép null vào các MCP tool thông thường. Tắt để có tool surface nhỏ hơn, không dùng Session.
`live_workspace_enabled`	`LOCAL_SHELL_MCP_LIVE_WORKSPACE_ENABLED`	`True`	Công khai tools, resources và các route `/api/live/*` của MCP App Live Workspace. Yêu cầu `ui_enabled` và không khả dụng ở mode `stdio`.
`ui_enabled`	`LOCAL_SHELL_MCP_UI_ENABLED`	`True`	Mount native OpenTUI launcher, WebUI shell, PTY WebSocket và routes `/api/ui/*`.
`ui_path`	`LOCAL_SHELL_MCP_UI_PATH`	`'/ui'`	WebUI mount path trên cùng service.
`ui_tui_command`	`LOCAL_SHELL_MCP_UI_TUI_COMMAND`	`None`	Optional command override cho OpenTUI executable resolution.
`ui_wallpaper`	`LOCAL_SHELL_MCP_UI_WALLPAPER`	`'bing'`	`bing`, `aurora`, hoặc `none`.
`ui_terminal_idle_timeout_s`	`LOCAL_SHELL_MCP_UI_TERMINAL_IDLE_TIMEOUT_S`	`3600`	Inactive browser PTY timeout; `0` tắt timeout.
`ui_terminal_max_sessions`	`LOCAL_SHELL_MCP_UI_TERMINAL_MAX_SESSIONS`	`8`	Số concurrent browser OpenTUI PTYs tối đa.

Remote workers¶

YAML key	Environment variable	Default	Ghi chú
`remote_enabled`	`LOCAL_SHELL_MCP_REMOTE_ENABLED`	`True`	Điều khiển `/join`, `/remote/` và MCP tools `remote_`.
`remote_invite_ttl_s`	`LOCAL_SHELL_MCP_REMOTE_INVITE_TTL_S`	`600`
`remote_poll_timeout_s`	`LOCAL_SHELL_MCP_REMOTE_POLL_TIMEOUT_S`	`25`
`remote_job_timeout_s`	`LOCAL_SHELL_MCP_REMOTE_JOB_TIMEOUT_S`	`3600`
`remote_max_pending_jobs`	`LOCAL_SHELL_MCP_REMOTE_MAX_PENDING_JOBS`	`256`	Số queued/pending jobs tối đa mỗi worker.
`remote_cancelled_job_ttl_s`	`LOCAL_SHELL_MCP_REMOTE_CANCELLED_JOB_TTL_S`	`3600`	Retention time của cancellation tombstones dùng để bỏ qua timed-out queued jobs.
`remote_transfer_strategy`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_STRATEGY`	`'auto'`	`auto`, `relay`, `direct`, hoặc `object_store`. `auto` thử enabled peer-direct, configured S3 rồi bounded-memory controller relay.
`remote_peer_transfer_enabled`	`LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_ENABLED`	`False`	Tùy chọn bật one-shot HTTP receiver trên destination worker cho direct worker-to-worker transfer. Chỉ bật trên trusted private network như VPC/Tailscale.
`remote_peer_transfer_bind_host`	`LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_BIND_HOST`	`'0.0.0.0'`	Bind address của one-shot receiver trên destination worker.
`remote_peer_transfer_advertise_host`	`LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_ADVERTISE_HOST`	`None`	Address quảng bá cho source worker; default là destination worker hostname/FQDN.
`remote_peer_transfer_port`	`LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_PORT`	`0`	Receiver port; `0` chọn ephemeral port.
`remote_peer_transfer_timeout_s`	`LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_TIMEOUT_S`	`3600`	Lifetime/timeout của one-shot direct receiver.
`remote_transfer_s3_bucket`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_BUCKET`	`None`	Optional S3-compatible bucket cho presigned worker-to-worker transfers. Cần extra `s3`.
`remote_transfer_s3_prefix`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_PREFIX`	`'local-shell-mcp'`	Object-key prefix cho temporary transfer objects.
`remote_transfer_s3_region`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_REGION`	`None`	Optional S3 region.
`remote_transfer_s3_endpoint_url`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_ENDPOINT_URL`	`None`	Optional S3-compatible endpoint URL.
`remote_transfer_s3_presign_ttl_s`	`LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_PRESIGN_TTL_S`	`3600`	Lifetime của presigned PUT/GET URL. Temporary objects bị xóa sau transfer.

Shell và executable paths¶

YAML key	Environment variable	Default	Ghi chú
`shell_executable`	`LOCAL_SHELL_MCP_SHELL_EXECUTABLE`	`'/bin/bash'`
`shell_env_blocklist`	`LOCAL_SHELL_MCP_SHELL_ENV_BLOCKLIST`	`['CLOUDFLARE_TUNNEL_TOKEN']`
`shell_env_blocked_prefixes`	`LOCAL_SHELL_MCP_SHELL_ENV_BLOCKED_PREFIXES`	`['LOCAL_SHELL_MCP_', 'DOCKER_']`	Comma-separated trong environment variables; list trong YAML.
`tmux_bin`	`LOCAL_SHELL_MCP_TMUX_BIN`	`'tmux'`	Preferred tmux executable. Nếu không có, Linux releases và Docker builds dùng bundled helper; nếu không thì persistent shells fallback sang native backend.
`rg_bin`	`LOCAL_SHELL_MCP_RG_BIN`	`'rg'`
`git_bin`	`LOCAL_SHELL_MCP_GIT_BIN`	`'git'`
`python_bin`	`LOCAL_SHELL_MCP_PYTHON_BIN`	`'python3'`

Authentication và OAuth¶

YAML key	Environment variable	Default	Ghi chú
`auth_mode`	`LOCAL_SHELL_MCP_AUTH_MODE`	`'oauth'`	Dùng `oauth` cho public deployments.
`auth_bypass_localhost`	`LOCAL_SHELL_MCP_AUTH_BYPASS_LOCALHOST`	`True`
`require_auth_for_mcp_discovery`	`LOCAL_SHELL_MCP_REQUIRE_AUTH_FOR_MCP_DISCOVERY`	`True`	Yêu cầu OAuth trước MCP initialization và tool discovery.
`mcp_session_idle_timeout_s`	`LOCAL_SHELL_MCP_MCP_SESSION_IDLE_TIMEOUT_S`	`180`	Idle timeout cho Stateful Streamable HTTP sessions.
`mcp_max_sessions`	`LOCAL_SHELL_MCP_MCP_MAX_SESSIONS`	`1024`	Số concurrent stateful MCP sessions tối đa.
`public_base_url`	`LOCAL_SHELL_MCP_PUBLIC_BASE_URL`	`None`	External HTTPS origin. Không gồm `/mcp`.
`oauth_issuer`	`LOCAL_SHELL_MCP_OAUTH_ISSUER`	`None`
`oauth_resource`	`LOCAL_SHELL_MCP_OAUTH_RESOURCE`	`None`
`oauth_admin_pin`	`LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN`	`None`
`oauth_jwt_secret`	`LOCAL_SHELL_MCP_OAUTH_JWT_SECRET`
`oauth_access_token_ttl_s`	`LOCAL_SHELL_MCP_OAUTH_ACCESS_TOKEN_TTL_S`	`0`	`0` nghĩa là access tokens không tự expire.
`oauth_code_ttl_s`	`LOCAL_SHELL_MCP_OAUTH_CODE_TTL_S`	`300`

Built-in policy lists¶

YAML key	Environment variable	Default	Ghi chú
`command_denylist`	`LOCAL_SHELL_MCP_COMMAND_DENYLIST`	`[]`	Tự động clear khi full-container mode bật.
`path_denylist`	`LOCAL_SHELL_MCP_PATH_DENYLIST`	`[]`	Tự động clear khi full-container mode bật.

Ví dụ YAML¶

host: 0.0.0.0
port: 8765
mode: mcp
workspace_root: /workspace
auth_mode: oauth
remote_enabled: true
disable_local: false
logical_sessions_enabled: true
live_workspace_enabled: true
ui_enabled: true
ui_path: /ui
file_download_enabled: true
shell_env_blocked_prefixes:
  - LOCAL_SHELL_MCP_
  - DOCKER_

Serverless controller với durable Redis state:

mode: mcp
stateless_controller: true
state_backend: redis
state_backend_url: redis://redis.internal:6379/0
remote_transfer_strategy: auto

stateless_controller loại bỏ nhu cầu persistent controller volume. Backend memory cố ý ephemeral: cold start làm invalid pending remote invites và worker identities, đồng thời loại OAuth clients, jobs và audit records. Dùng Redis khi state đó phải tồn tại qua cold starts, kể cả durable worker revocation semantics. Với default auth_mode=oauth, inject ít nhất 32 bytes random key material qua LOCAL_SHELL_MCP_OAUTH_JWT_SECRET. Active remote RPC queues/futures là process-local, vì vậy deployment dùng remote workers hiện nên chạy một active controller instance thay vì nhiều load-balanced controller replicas.

Khuyến nghị vận hành¶

Giữ allow_full_container=false trừ khi container/VM disposable.
Giữ auth_mode=oauth cho mọi public endpoint.
Tắt remote_enabled nếu không dùng remote workers.
Tắt file_download_enabled nếu không bao giờ cần artifacts tải từ chat.
Đặt limit command, file, audit đủ cao cho coding tasks nhưng đủ thấp để tránh accidental runaway output.