Lewati ke isi

Konfigurasi

Repository menyediakan satu starter file yang dapat disalin: .env.example. Docker Compose membaca .env hasilnya secara otomatis, dan runtime lain dapat memakai environment variables LOCAL_SHELL_MCP_ yang sama. YAML tetap menjadi optional advanced input untuk deployment binary atau source; buat file secara eksplisit dan pilih dengan LOCAL_SHELL_MCP_CONFIG atau --config. Environment variables override YAML values, jadi hindari mendefinisikan setting yang sama di keduanya kecuali override memang disengaja. YAML keys menggunakan field names di bawah.

Precedence

  1. Built-in defaults dari Settings.
  2. YAML config yang dipilih oleh LOCAL_SHELL_MCP_CONFIG atau --config.
  3. Environment variables dengan prefix LOCAL_SHELL_MCP_.
  4. CLI flags seperti --mode, --config, --remote, dan --no-remote, yang mengatur environment values terkait sebelum 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

Untuk local-only testing, auth_bypass_localhost aktif secara default. Jangan expose unauthenticated full MCP tools di public network.

Settings reference

Server dan workspace

YAML key Environment variable Default Catatan
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 untuk Uvicorn forwarded-header handling. Gunakan * hanya jika direct ingress dibatasi.
mode LOCAL_SHELL_MCP_MODE 'mcp' mcp, http, stdio, atau nilai 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 Menonaktifkan workspace/path restrictions ketika true; gunakan hanya dalam disposable boundaries.
disable_local LOCAL_SHELL_MCP_DISABLE_LOCAL False Menonaktifkan controller host sebagai target eksekusi shell/file/browser. Remote workers dan control-plane services tetap tersedia.
stateless_controller LOCAL_SHELL_MCP_STATELESS_CONTROLLER False Membuat controller cocok untuk instance ephemeral/serverless: mengimplikasikan disable_local, menonaktifkan local file links/wallpaper caching, dan default state_backend menjadi memory. Dengan auth_mode=oauth, konfigurasi oauth_jwt_secret yang kuat secara eksplisit.
state_backend LOCAL_SHELL_MCP_STATE_BACKEND 'file' file, memory, atau redis. Gunakan Redis jika serverless controller state harus bertahan melewati cold starts.
state_backend_url LOCAL_SHELL_MCP_STATE_BACKEND_URL None Redis connection URL saat state_backend=redis. Redacted dalam diagnostics.
state_backend_prefix LOCAL_SHELL_MCP_STATE_BACKEND_PREFIX 'local-shell-mcp' Namespace untuk memory/Redis control-plane state.

Batas

YAML key Environment variable Default Catatan
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 Maksimum Skill directories yang dikembalikan satu registry scan.
max_skill_related_files LOCAL_SHELL_MCP_MAX_SKILL_RELATED_FILES 1000 Maksimum related files yang dikembalikan untuk satu Skill.
max_skill_scan_entries LOCAL_SHELL_MCP_MAX_SKILL_SCAN_ENTRIES 5000 Maksimum filesystem entries yang diperiksa oleh satu skill_list registry scan atau direct Skill load.
max_skill_path_bytes LOCAL_SHELL_MCP_MAX_SKILL_PATH_BYTES 200000 Maksimum UTF-8 bytes yang dipakai 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 Maksimum buffered HTTP request body di endpoint MCP, REST, OAuth, UI, dan remote-worker.
max_job_log_bytes LOCAL_SHELL_MCP_MAX_JOB_LOG_BYTES 10000000 Maksimum retained output bytes untuk setiap long-running job attempt.
max_jobs LOCAL_SHELL_MCP_MAX_JOBS 1000 Maksimum retained long-running job records; active jobs tidak pernah 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 Maksimum entries yang diterima saat unpack transferred directory archive.
max_transfer_unpacked_bytes LOCAL_SHELL_MCP_MAX_TRANSFER_UNPACKED_BYTES 10000000000 Maksimum declared expanded bytes yang diterima untuk transferred directory archive.
max_concurrent_commands LOCAL_SHELL_MCP_MAX_CONCURRENT_COMMANDS 4
max_tmux_sessions LOCAL_SHELL_MCP_MAX_TMUX_SESSIONS 16 Maksimum persistent shell sessions di backend tmux, ConPTY, dan native fallback.
YAML key Environment variable Default Catatan
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 berarti tidak ada default download-count limit.
file_download_max_file_bytes LOCAL_SHELL_MCP_FILE_DOWNLOAD_MAX_FILE_BYTES 0 0 berarti tidak ada configured file-size cap untuk download links.

Human interface

YAML key Environment variable Default Catatan
logical_sessions_enabled LOCAL_SHELL_MCP_LOGICAL_SESSIONS_ENABLED True Mengekspos session_manage dan plan_manage serta menambahkan argumen logical_session_id yang wajib tetapi nullable ke tool MCP biasa. Nonaktifkan untuk tool surface yang lebih kecil tanpa Session.
live_workspace_enabled LOCAL_SHELL_MCP_LIVE_WORKSPACE_ENABLED True Mengekspos tool, resource, dan route /api/live/* MCP App Live Workspace. Memerlukan ui_enabled dan tidak tersedia dalam mode stdio.
ui_enabled LOCAL_SHELL_MCP_UI_ENABLED True Mount native OpenTUI launcher, WebUI shell, PTY WebSocket, dan routes /api/ui/*.
ui_path LOCAL_SHELL_MCP_UI_PATH '/ui' WebUI mount path pada service yang sama.
ui_tui_command LOCAL_SHELL_MCP_UI_TUI_COMMAND None Optional command override untuk OpenTUI executable resolution.
ui_wallpaper LOCAL_SHELL_MCP_UI_WALLPAPER 'bing' bing, aurora, atau none.
ui_terminal_idle_timeout_s LOCAL_SHELL_MCP_UI_TERMINAL_IDLE_TIMEOUT_S 3600 Inactive browser PTY timeout; 0 menonaktifkannya.
ui_terminal_max_sessions LOCAL_SHELL_MCP_UI_TERMINAL_MAX_SESSIONS 8 Maksimum concurrent browser OpenTUI PTYs.

Remote workers

YAML key Environment variable Default Catatan
remote_enabled LOCAL_SHELL_MCP_REMOTE_ENABLED True Mengontrol /join, /remote/*, dan 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 Maksimum queued/pending jobs per worker.
remote_cancelled_job_ttl_s LOCAL_SHELL_MCP_REMOTE_CANCELLED_JOB_TTL_S 3600 Retention time cancellation tombstones yang dipakai untuk melewati timed-out queued jobs.
remote_transfer_strategy LOCAL_SHELL_MCP_REMOTE_TRANSFER_STRATEGY 'auto' auto, relay, direct, atau object_store. auto mencoba enabled peer-direct, configured S3, lalu bounded-memory controller relay.
remote_peer_transfer_enabled LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_ENABLED False Secara opsional mengaktifkan one-shot HTTP receiver pada destination worker untuk direct worker-to-worker transfer. Aktifkan hanya pada trusted private network seperti VPC/Tailscale.
remote_peer_transfer_bind_host LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_BIND_HOST '0.0.0.0' Bind address one-shot receiver pada destination worker.
remote_peer_transfer_advertise_host LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_ADVERTISE_HOST None Address yang diumumkan kepada source worker; default destination worker hostname/FQDN.
remote_peer_transfer_port LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_PORT 0 Receiver port; 0 memilih ephemeral port.
remote_peer_transfer_timeout_s LOCAL_SHELL_MCP_REMOTE_PEER_TRANSFER_TIMEOUT_S 3600 Lifetime/timeout one-shot direct receiver.
remote_transfer_s3_bucket LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_BUCKET None Optional S3-compatible bucket untuk presigned worker-to-worker transfers. Memerlukan extra s3.
remote_transfer_s3_prefix LOCAL_SHELL_MCP_REMOTE_TRANSFER_S3_PREFIX 'local-shell-mcp' Object-key prefix untuk 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 presigned PUT/GET URL. Temporary objects dihapus setelah transfer.

Shell dan executable paths

YAML key Environment variable Default Catatan
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 dalam environment variables; list dalam YAML.
tmux_bin LOCAL_SHELL_MCP_TMUX_BIN 'tmux' Preferred tmux executable. Jika tidak tersedia, Linux releases dan Docker builds memakai bundled helper; selain itu persistent shells fallback ke 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 dan OAuth

YAML key Environment variable Default Catatan
auth_mode LOCAL_SHELL_MCP_AUTH_MODE 'oauth' Gunakan oauth untuk 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 Mewajibkan OAuth sebelum MCP initialization dan tool discovery.
mcp_session_idle_timeout_s LOCAL_SHELL_MCP_MCP_SESSION_IDLE_TIMEOUT_S 180 Idle timeout untuk Stateful Streamable HTTP sessions.
mcp_max_sessions LOCAL_SHELL_MCP_MCP_MAX_SESSIONS 1024 Maksimum concurrent stateful MCP sessions.
public_base_url LOCAL_SHELL_MCP_PUBLIC_BASE_URL None External HTTPS origin. Jangan sertakan /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 berarti access tokens tidak expire otomatis.
oauth_code_ttl_s LOCAL_SHELL_MCP_OAUTH_CODE_TTL_S 300

Built-in policy lists

YAML key Environment variable Default Catatan
command_denylist LOCAL_SHELL_MCP_COMMAND_DENYLIST [] Dikosongkan otomatis saat full-container mode aktif.
path_denylist LOCAL_SHELL_MCP_PATH_DENYLIST [] Dikosongkan otomatis saat full-container mode aktif.

Contoh 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 dengan 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 menghilangkan kebutuhan persistent controller volume. Backend memory sengaja ephemeral: cold start menginvalidasi pending remote invites dan worker identities serta membuang OAuth clients, jobs, dan audit records. Gunakan Redis jika state tersebut harus bertahan melewati cold starts, termasuk durable worker revocation semantics. Dengan default auth_mode=oauth, inject minimal 32 bytes random key material melalui LOCAL_SHELL_MCP_OAUTH_JWT_SECRET. Active remote RPC queues/futures bersifat process-local, sehingga deployment yang memakai remote workers saat ini sebaiknya menjalankan satu active controller instance, bukan beberapa load-balanced controller replicas.

Saran operasional

  • Pertahankan allow_full_container=false kecuali container/VM disposable.
  • Pertahankan auth_mode=oauth untuk setiap public endpoint.
  • Nonaktifkan remote_enabled jika tidak memakai remote workers.
  • Nonaktifkan file_download_enabled jika tidak pernah butuh artifacts yang dapat di-download dari chat.
  • Atur limit command, file, dan audit cukup tinggi untuk coding tasks namun cukup rendah untuk mencegah accidental runaway output.