AI Support Agent CLI

A daemon that turns your machine into an AI-powered remote agent. Install it, authenticate via browser, and your team can send shell commands, AI chat prompts, file operations, and more — all from a Web UI, with results streamed back in real time.

┌──────────────┐  AppSync     ┌─────────────────┐  WebSocket/HTTP  ┌──────────────────┐
│   Web UI     │ ──────────── │   API Server    │ ─────────────── │  Agent CLI       │
│  (browser)   │  subscription│   (NestJS)      │  commands/result │  (your machine)  │
└──────────────┘              └─────────────────┘                  └──────────────────┘
                                                                     ├─ Claude Code
                                                                     ├─ Shell / PTY
                                                                     ├─ File I/O
                                                                     ├─ Git repos
                                                                     ├─ MCP server
                                                                     └─ VS Code tunnel

Why?

• Remote AI pair-programming — Ask questions about your codebase from the Web UI; Claude Code runs on the agent machine with full repository access.
• Multi-tenant, multi-project — A single agent manages multiple projects across different tenants. Add/remove projects on the fly; the agent hot-reloads.
• Zero-config realtime — AppSync WebSocket subscriptions deliver commands instantly. No polling delay, no port forwarding.
• Secure by default — OAuth login, 0600 config permissions, nonce-protected callbacks, SQL injection detection, path traversal guards, and environment sanitization.

Hosted Service

The quickest way to get started is with the managed service at ai-support-agent.com. Create an account there, then the CLI connects to it out of the box — these are the built-in defaults, so no extra flags are needed:

Running ai-support-agent login opens the hosted web console (app.ai-support-agent.com) in your browser, where you sign in and pick the tenant and project to link.

Self-hosting? The CLI is not tied to the hosted service. Point it at your own deployment with --url / --api-url (or the AI_SUPPORT_AGENT_API_URL environment variable) — see Configuration.

Quick Start

npm install -g @ai-support-agent/cli

# Opens app.ai-support-agent.com in your browser → sign in → select tenant & project → done
ai-support-agent login

# Start the daemon (Ctrl-C to stop)
ai-support-agent start

That's it. The agent registers with the server, syncs project config, clones repositories, and starts listening for commands.

Docker must be running: each project runs in a container by default, and the first start obtains the agent image (see Run in Docker). Add --no-docker to run natively on the host instead.

Add more projects

ai-support-agent add-project          # browser OAuth flow
ai-support-agent status               # verify registered projects

Start with a Personal Access Token (agent scope)

Instead of the browser OAuth flow, you can start an agent with a Personal Access Token (PAT) that you issue for yourself in the web app. Issue a PAT whose scope includes agent and whose projectCode is set, then start the agent under your own permissions ("personal plan"):

# The tenant comes from the token; the project is given with --project.
ai-support-agent start --token <tenantCode>:<tokenId>:<rawToken> --project <tenantCode>/<projectCode>

• No browser login and no prior login/configure step is required.
• --api-url is optional and defaults to the production API (https://api.ai-support-agent.com).
• The tenant in --project must match the tenant the PAT was issued for; a mismatch is rejected before the agent registers.
• Prefer passing the token via the AI_SUPPORT_AGENT_TOKEN environment variable so it does not appear in process listings (ps aux).

Run in Docker

Docker is the default: plain ai-support-agent start runs each project in a container, and --no-docker opts out into native mode.

ai-support-agent start              # Docker mode (default)
ai-support-agent start --no-docker  # run natively on the host instead

Project dirs, ~/.claude/, and ~/.aws/ are auto-mounted. The container runs with your host UID/GID.

Base image. The first run of a given version obtains ai-support-agent:<version>:

The published image is built by this repository's release workflow from the same docker/Dockerfile and the same CLI version, so for an unmodified setup pulling and building produce the same image.

Once the image exists locally it is reused as-is — customising the Dockerfile afterwards does not trigger a rebuild. Use:

ai-support-agent docker-diff-dockerfile   # compare your Dockerfile with the bundled default
ai-support-agent docker-build             # force a local rebuild after customising
ai-support-agent docker-ensure-image      # obtain the image if missing (pull or build)

Run as a background service

ai-support-agent service install      # install as a system service
ai-support-agent service start        # start the service
ai-support-agent service status       # check service status
ai-support-agent service stop         # stop the service
ai-support-agent service restart      # restart the service
ai-support-agent service uninstall    # remove the service

How It Works

1. Register — Agent sends its capabilities (shell, file I/O, chat, terminal, vscode) to the API.
2. Subscribe — Connects to AppSync for real-time command delivery.
3. Config sync — Pulls project settings, MCP config, and repo list from the server.
4. Execute — Receives commands, runs them locally, streams results back chunk-by-chunk.

Each project runs in its own forked child process. The main process watches config.json and hot-adds/removes projects without restart.

Supported Commands

Chat Modes

The mode is resolved as: agent config → server default → auto-detection (whether claude CLI is installed).

Built-in MCP Server

The agent ships a Model Context Protocol server that Claude Code can call:

General tools:

Browser automation tools (Playwright-based):

E2E test tools:

CLI Reference

ai-support-agent <command> [options]

Commands:
  start              Start the agent daemon
  stop               Stop the running agent
  login              Authenticate via browser OAuth
  add-project        Add a project (browser OAuth)
  remove-project     Remove a project by code
  configure          Register with --token and --api-url
  status             Show agent status and registered projects
  set-language       Set display language (en | ja)
  set-auto-update    Configure auto-update (--enable | --disable | --channel)
  set-project-dir    Set project working directory
  docker-login       Login and start in Docker
  docker-build       Always build the Docker image for this version locally
                     (--dockerfile <path>)
  docker-ensure-image  Make the Docker image available: pull
                     ghcr.io/mbc-net/ai-support-agent-cli when nothing is
                     customised, build locally otherwise (--dockerfile <path>,
                     --no-image-pull)
  docker-diff-dockerfile  Show diff between a Dockerfile and the bundled default
  log-rotate         Read stdin and write to a size-rotating log file
                     (used by the per-project wrapper script)
  service            Manage agent background service

Global options:
  --lang <lang>      Override display language for this invocation
  --version          Show version

service Subcommands

service install     Install the agent as a system background service
service uninstall   Uninstall the agent service
service start       Start the agent service
service stop        Stop the agent service
service restart     Restart the agent service
service status      Show service status

Options (install):
  --verbose          Show detailed installation info
  --no-docker        Install in native mode (skip Docker)

start Options

--token <token>            Auth token or agent-scoped PAT (overrides config file)
--api-url <url>            API URL (defaults to the production API)
--verbose                  Enable debug logging
--heartbeat-interval <ms>  Heartbeat interval (default: 60000)
--no-auto-update           Disable auto-update for this session
--update-channel <channel> Release channel: latest | beta | alpha
--no-docker                Force native mode (skip Docker)
--dockerfile <path>        Custom Dockerfile path (overrides config and bundled default)
--no-dockerfile-sync       Skip writing the default Dockerfile to config dir
--no-image-pull            Never pull the base image from the container registry;
                           always build it locally (same as config
                           "dockerImagePull": "never"). By default an
                           uncustomised Dockerfile means the published
                           ghcr.io/mbc-net/ai-support-agent-cli image is pulled
                           instead of being rebuilt on this machine
--project <tenantCode/projectCode>  Start only the matching project; with --token
                                    it selects the project for a direct (PAT) start

set-project-dir Options

--default <template>       Set default dir template (e.g. ~/projects/{projectCode})
--project <code> --path <path>  Set dir for a specific project

Configuration

Stored at ~/.ai-support-agent/config.json (mode 0600):

{
  "agentId": "macbook-a1b2c3d4",       // auto-generated
  "createdAt": "2025-01-01T00:00:00Z",
  "lastConnected": "2025-06-15T09:00:00Z",
  "language": "en",                     // en | ja
  "agentChatMode": "claude_code",       // claude_code | api
  "defaultProjectDir": "~/.ai-support-agent/projects/{projectCode}",
  "autoUpdate": {
    "enabled": true,
    "autoRestart": true,
    "channel": "latest"                 // latest | beta | alpha
  },
  "projects": [
    {
      "projectCode": "MY_PROJECT",
      "token": "agt_xxxx",
      "apiUrl": "https://api.ai-support-agent.com",   // defaults to the hosted API
      "projectDir": "~/custom-path"     // optional override
    }
  ]
}

Environment Variables

Priority: CLI flags > config file > environment variables.

Project Directory Structure

Each project gets an isolated workspace:

{projectDir}/
├── workspace/
│   ├── repos/          # Git-cloned repositories
│   ├── docs/           # Documentation from server
│   └── artifacts/      # Generated outputs
├── uploads/            # File uploads staging
└── .ai-support-agent/
    ├── cache/          # Temporary cache
    └── aws/            # AWS credential cache

Security

Development

git clone https://github.com/mbc-net/ai-support-agent-cli.git
cd ai-support-agent-cli

npm install
npm run dev -- start --verbose    # development mode
npm test                          # run tests
npm run test:cov                  # coverage (95%+ thresholds enforced)
npm run build                     # compile to dist/

Requires Node.js >= 20. node-pty is an optional dependency for terminal/PTY sessions.

License

MIT

環境設定・秘密情報Vault

auth login/logout と env check/run/pull で承認済み環境設定を利用できます。 導入・権限・運用制約は 環境Vaultガイド を参照してください。

.envを使うローカル開発（日本語）

Vault対応API・Webを導入してVaultを有効化し、管理画面で local の設定リリースを承認・有効化します。利用者にはファイル出力用の export 権限を付与してください。

開発プロジェクトの .ai-support/env.yaml に接続先と識別子を設定します。秘密値はここへ書きません。

version: 1
apiUrl: https://api.example.test
tenant: example
project: support
profiles:
  local:
    service: api
    environment: local
    required: [DATABASE_URL]

.gitignore に .env.local を追加し、プロジェクトのルートで実行します。URLと識別子は実際の環境に置き換えてください。

ai-support-agent auth login --url https://app.example.test --profile local --purpose export
# ブラウザーでログインし、設定取得を許可します。
ai-support-agent env pull --profile local --output .env.local
ai-support-agent auth logout --profile local --purpose export

.env が必要な場合はGitignoreの指定と出力先を両方変更します。既存ファイルへの上書きはしません。ファイルを作らず開発する場合は run 権限を付与し、--purpose export を付けずにログインして ai-support-agent env run --profile local -- npm run dev を実行します。

Vaultの設定編集とセッション時間

auth login --purpose edit --session-duration 8h で編集用ログインを行い、 env add LOG_LEVEL --value debug／env set LOG_LEVEL --value info で未承認の候補を作成します。 複数変更は前の候補IDを --from へ指定します。秘密値は --secret の非表示入力、または --secret --stdin を使用します。秘密値を --value に渡すことは禁止しています。 標準入力の末尾改行は保持し、除去する場合のみ --strip-final-newline を指定してください。

env diff --release <ID> → env approve --release <ID> → 各配布先への env stage --release <ID> --target <ID> → env activate --release <ID> --expected-active <現在のID> の順で反映します。承認はapprove、配布・有効化はdeploy用途で別にログインします。 初回有効化の --expected-active は none、localではstageを省略できます。 本番では変更参加者による自己承認を拒否します。

localの実行・管理と開発／テストの管理セッションは最大8時間、exportと本番管理は最大1時間です。 管理者の設定により短くなることがあります。期限内はOS資格情報ストアのセッションを再利用し、 自動更新はしません。実行用リースは別管理のままです。 通信切断後は表示されたIDを env status --operation-id <ID> --purpose <用途> で確認し、 同じ要求を再送する場合だけ同じ --operation-id を使用します。再送可能期間は24時間です。

E2E configuration migration

Deploy the API with command-scoped E2E configuration endpoints before deploying this agent. Every E2E execution mode performs a command-bound admission check before starting; the agent never falls back to the old environment-only endpoint. Completion uses a separate acknowledgement after terminal command-result submission. Failed acknowledgements retain the original result for retry.

Configuration admission remains active when a child is still running, termination used a signal/kill/timeout, or browser-session cleanup failed. Normal completion relies on the supported runner's ordinary browser/worker teardown; scripts must not detach background processes. Historical jobs and independently detached descendants require verified operator shutdown before v2 migration. A terminal execution status alone is not proof that those processes stopped.

Server setup configuration completion

Server setup result delivery and configuration admission closure are separate acknowledgements. The agent persists runner-observed completion evidence alongside a pending result, submits the ordinary result first, then submits /agent/commands/:id/server-setup-configuration-complete. A lost acknowledgement retains the original result, evidence, instance identity and assignment for retry. The API must support identical result replays after accepting a terminal result. Tokens are not extended by this protocol; expired credentials require operator reconciliation.

Automatic ordinary completion currently covers direct synchronous debug/assert/set_fact, copy/file/lineinfile/blockinfile/replace/stat/get_url/group/user/wait_for and authorized_key modules, after successful Ansible process completion and valid task output. Async/poll/notify and arbitrary validation commands are excluded. Shell/command tasks and unaudited bundled roles remain unresolved even when the UI reports success. Their remote termination must be reconciled before configuration cutover. An intended service daemon continuing to run is not itself an unfinished recipe task; extending automatic coverage requires auditing the recipe's task lifecycle rather than requiring every service to stop.

Sentry completion uses the dedicated remote-state probe, requiring an explicit settled: true, active: false and a matching installation run ID. Standalone successful recovery operations retain the observed remote run ID for host-scoped server reconciliation. Mixed recipes must also have synchronously certifiable companion tasks and finish locally without timeout or cancellation. SSH loss, missing probe fields, local process termination alone, and UI terminal status are never evidence of remote Sentry termination.

Each setup claim also carries x-server-setup-instance-id, generated before command retrieval and retained with the pending result. Recovered results restore the original identity; a restarted process must not fetch and execute the command again. Resident assignment generation and replica identity continue to be checked independently. The runner records data.serverSetupLocalTermination only after the Ansible child's observed close event, excluding spawn failures; an execFile error callback alone is insufficient. This is local termination evidence, including after a timeout/cancel that actually closed the child; it cannot establish remote termination. Recovery of an earlier Sentry admission must combine its authenticated saved local proof with appropriately scoped remote proof. Legacy executions without that evidence remain blocked for operator reconciliation.

Sentry admission closure additionally requires the original Ansible run to finish successfully. A settled remote snapshot after cancellation, timeout or other failed execution does not exclude an already-dispatched delayed remote start. Such admissions remain unresolved until stronger remote fencing or independently verified operational termination is available.