AgentCell client

AgentCell is an AI-native deployment platform for small web apps and internal tools: the apps you or a coding agent build for one person or a small team. It runs your web app in its own isolated cell at https://<cell>.agentcell.cloud. This is the client: one static binary that is both the human CLI and the MCP server for coding agents. It needs no Docker, Python, or repository checkout at runtime.

Get started (three commands)

1. Install. Download the binary for your machine from the latest release, verify it against SHA256SUMS, and put it on your PATH as agentcell:

   curl -fsSLO https://github.com/AgentCell-dev/agentcell-client/releases/download/v0.1.4/agentcell_0.1.4_darwin_arm64
   curl -fsSLO https://github.com/AgentCell-dev/agentcell-client/releases/download/v0.1.4/SHA256SUMS
   grep agentcell_0.1.4_darwin_arm64 SHA256SUMS | shasum -a 256 -c -
   chmod +x agentcell_0.1.4_darwin_arm64 && mv agentcell_0.1.4_darwin_arm64 /usr/local/bin/agentcell

   Or keep it in the current directory and call ./agentcell: skip the last mv and instead run mv agentcell_0.1.4_darwin_arm64 agentcell (the chmod +x above still applies).

   Replace darwin_arm64 with darwin_amd64, linux_amd64, linux_arm64, or windows_amd64.exe, and 0.1.4 (in the tag and in the file name) with the newest release on the releases page (the latest alias cannot carry a versioned filename, which is why the tag is spelled out). Or, with Go 1.25 installed: go install github.com/AgentCell-dev/agentcell-client/cmd/agentcell@latest.

2. Log in. This opens your browser; sign in with Google, GitHub, or a one-time PIN sent to your email. Your account and a personal organisation are created on first login.

   agentcell login

   On a machine without a browser, agentcell login --no-browser prints a link and a code: open the link on any device, check the page shows the same code, and press Authorise. Only ever press Authorise for a code a terminal in front of you is showing.

3. Deploy. From the directory holding your app:

   agentcell deploy --cell my-app .

   The command prints the URL. agentcell logs my-app streams the app's output; agentcell ps lists your cells; agentcell whoami shows who you are logged in as.

What deploy accepts. It reads the root of the directory and uses the first of three shapes that matches:

• a Dockerfile: one container, listening on the port its EXPOSE names (8080 when it names none), with /data for anything that must survive a restart;
• a package.json with a build script: a static site built on the platform (npm ci when package-lock.json is present, otherwise npm install, then npm run build), serving the first of dist/, build/ and out/ that holds an index.html. Vite, Create React App, Vue, Svelte and Astro builds work this way;
• an index.html: a static site served as-is, with no build.

A static site gets the same private https://<cell>.agentcell.cloud hostname and sign-in as every cell, but no port or /data: the platform's edge serves the files and no container runs for it. agentcell logs --build shows a built site's build output. /about redirects to /about/ when about/index.html exists, and otherwise serves about.html. A site with no 404.html answers an unknown path with no file extension with index.html, so client-side routes in a single-page app work; add a 404.html to turn that off. Files and folders whose names begin with . are not published, except .well-known/. In package.json, "agentcell": {"output": "public", "spa": false} overrides the output folder and the single-page fallback. Next.js needs output: 'export' in next.config (it writes out/) or a Dockerfile. The client leaves node_modules/ and the .next/, .svelte-kit/, .turbo/, .parcel-cache/ and .vite/ caches out of every upload, at any depth, and sends dist/, build/ and out/ (0.1.4 and later; an older client uploads node_modules/ and a frontend project usually exceeds the upload limit).

Working examples to start from: AgentCell-dev/samples (plain HTML and a Vite + React app as static sites; a notes app on SQLite, a Go service, a Node worker, Next.js, FastAPI and Streamlit as containers), each with a README.

For coding agents: agentcell mcp is an MCP server over stdio exposing the same operations as tools; log in once with agentcell login and point your agent's MCP configuration at the binary. See docs/mcp-harness.md. Decision criteria for when AgentCell is the right target, and setup for Claude Code, Codex and Cursor: https://agentcell.dev/docs/for-ai-agents.md

agentcell deploy --cell my-app ./my-app
agentcell mcp

When stdout is a terminal output is human-readable; otherwise it is JSON. --output=human|json overrides detection. logs is the one streaming operation and emits one JSON object per line in machine mode.

Scheduled cells — ships with the service change; not live yet. agentcell deploy --schedule "<cron>" . runs the container to completion on a cadence instead of serving HTTP: five cron fields or @hourly/@daily/@weekly/@monthly, always UTC, at most once every 5 minutes. A scheduled cell has no URL; /data is kept between runs; ps reports the last run, its exit code and the next run, and logs shows the most recent run. The schedule is fixed for the life of the cell. This client already sends the field (the MCP deploy tool has the same schedule property), but a service older than the schedule support ignores it: against one, a deploy with --schedule is deployed as an ordinary web cell. That is why the client release carrying this flag waits for the service. Do not use it until this paragraph loses its "not live yet".

Credentials and the harness

Two credentials open two different doors — an API token (deploy/read/ secrets/admin) goes to the control plane, a cells-scoped token goes to a cell hostname and is verified by the auth Worker. They are not interchangeable. See docs/credentials.md for which is which and how to get each, and docs/mcp-harness.md for configuring a real coding harness against agentcell mcp (config snippet, the 11-tool surface, and the standing deploy-and-logs round-trip proof).

Contract and implementation boundary

contract.Definitions is the only verb declaration. Each entry has its name, summary, concrete Go request and response types, streaming bit, and destructive bit. CLI help/commands, argument binding, MCP tools/descriptions/schemas, and HTTP routes all derive from it. contract.Operations has two methods because streaming changes lifetime: Execute for request/response operations and Stream for logs. The public operations.HTTPClient implements it; the private service implements the same interface directly for in-process tests. No framework is needed for this boundary.

Destructive operations require an explicit request confirmation and, at the service boundary, a separately scoped capability token. Today only destroy is irreversible and therefore marked destructive; confirm must exactly equal cell_id. Mutating access, secret, and domain operations still require their own service-side capabilities. A deploy-only token must never authorize those verbs. The MCP server does not weaken this rule despite holding a standing token.

Deliberate protocol decisions

• API version: every request sends AgentCell-Version: 2026-08-01. A service supports a dated version for its compatibility window or returns unsupported_version with both versions. A breaking wire change gets a new date; adding optional fields or verbs is compatible.
• Idempotency: deterministic tar+gzip bytes are hashed as deploy-v1:<sha256> and sent both in the typed request and Idempotency-Key. The service must enforce uniqueness per organization and return the recorded deployment for a duplicate key. This survives an agent starting a new process to retry; a random per-process key would not. A --schedule is part of the key (deploy-v1:<sha256>.s<first 16 hex of sha256(schedule)>), so changing only the schedule is a new deploy rather than a replay; without one the key is exactly as above.
• Streaming: only logs is declared streaming. It uses newline-delimited JSON over HTTP and the separate Operations.Stream method.
• Tokens: AGENTCELL_TOKEN wins. Otherwise the file is under $XDG_CONFIG_HOME/agentcell, ~/.config/agentcell on Unix, or the platform config directory on Windows. Pipe an interim token to agentcell auth token for a machine credential an operator issued; agentcell login stores a personal one the same way. Neither is ever accepted as an argument or printed. Storage is behind an interface for a future keychain. login implements the loopback and RFC 8628 device flows against the platform's own /v1/auth/* endpoints; identity itself is verified by Cloudflare Access, not by this client.
• Dependencies: the current client is standard-library-only, so there is no go.sum yet. Once a module is added, go.sum is the required version-and-hash pin; no second hash mechanism is needed.

Gates and release

make lint test lint-selftest
make release VERSION=0.1.0

The dependency gate inspects the complete Go dependency graph and rejects the private github.com/agentcell/agentcell module. Its self-test introduces a resolvable private module and proves rejection. Surface parity is tested by appending one definition and requiring both CLI and MCP to gain it. Releases require exactly Go 1.25.5, cross-compile static binaries twice, compare the bytes, and publish SHA256SUMS beside them.