casapi
Stateless HTTP API for remote Claude Code execution powered by Claude Agent SDK.
Each request is one ephemeral claude_agent_sdk.query() run. There are no
sessions, no resume, and no server-side conversation state. A client on another
machine POSTs a prompt and receives the agent result plus the full message
transcript, either as one JSON document or as a Server-Sent Events stream.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health |
no | Readiness probe: {"status": "ok"} |
| GET | /v1/info |
yes | Server defaults and limits |
| POST | /v1/query |
yes | Run one agent query, return the transcript |
| POST | /v1/query/stream |
yes | Same, streamed as SSE |
See docs/api/rest-api.md for the full reference.
Quickstart
Server:
uv sync
export CASAPI_API_KEY="$(openssl rand -hex 32)"
export CASAPI_WORKSPACE_ROOT=/srv/workspaces
export ANTHROPIC_API_KEY=... # or log in with `claude` as the server user
uv run uvicorn casapi.main:app --host 127.0.0.1 --port 8000
Client (another machine, via TLS or a private network):
curl -sS https://casapi.example.net/v1/query \
-H "Authorization: Bearer $CASAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "List the files in this directory", "cwd": "myproject", "max_turns": 5}'
curl -N https://casapi.example.net/v1/query/stream \
-H "Authorization: Bearer $CASAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Summarize README.md"}'
Configuration
| Variable | Default | Description |
|---|---|---|
CASAPI_API_KEY |
unset | Bearer token clients must send |
CASAPI_ALLOW_UNAUTHENTICATED |
false |
Allow requests with no key configured (local dev only) |
CASAPI_WORKSPACE_ROOT |
current directory | All request cwd values must resolve inside this path |
CASAPI_DEFAULT_MODEL |
unset (SDK default) | Model used when a request omits model |
CASAPI_PERMISSION_MODE |
acceptEdits |
Default permission mode |
CASAPI_ALLOWED_TOOLS |
Read,Write,Edit,Bash,Glob,Grep |
Default auto-approve list (not a restriction; see below) |
CASAPI_ALLOW_BYPASS_PERMISSIONS |
false |
Permit requests with permission_mode=bypassPermissions |
CASAPI_MAX_CONCURRENCY |
4 |
Simultaneous runs; excess requests get HTTP 429 |
CASAPI_MAX_TIMEOUT_SECONDS |
3600 |
Default and maximum run duration |
Security model
- The API key is a shell. Holding the key is equivalent to running a shell as the service user (with the workspace as the starting directory). Protect it accordingly; everything below is defence in depth, not a sandbox.
- API key required by default. Without
CASAPI_API_KEY(or with an empty one), execution endpoints return 503 unlessCASAPI_ALLOW_UNAUTHENTICATED=trueis set explicitly. Keys are compared in constant time. allowed_toolsis an auto-approve list, not a restriction. It names the tools a run may use without a permission decision; it does not remove other tools, and under the defaultacceptEditsmode file edits are approved regardless. The server-sideCASAPI_ALLOWED_TOOLSis only a default — any key holder can send a different list per request.- The agent can read the server's secrets. A run inherits the service
environment, including
ANTHROPIC_API_KEY, the Claude login credentials, andCASAPI_API_KEYitself. Prompt-injected workspace content can therefore exfiltrate them; do not point the service at untrusted workspaces. - Workspace confinement. Request
cwdis resolved (symlinks included) and must stay insideCASAPI_WORKSPACE_ROOT. Note this confines the agent's starting directory, not what its tools (e.g.Bash) can reach; run the server as an unprivileged user or in a container for real isolation. bypassPermissionsis opt-in viaCASAPI_ALLOW_BYPASS_PERMISSIONS. It is not a meaningful boundary on its own: withBashauto-approved, the default posture is already shell-equivalent.- Client disconnects.
POST /v1/querypromptly cancels the run and frees its concurrency slot when the client disconnects. The streaming endpoint also cancels the run when its consumer goes away. - Bind and TLS. Bind to loopback or a private interface and put TLS in front (reverse proxy, Tailscale, or an SSH tunnel). The API key travels in a header.
- Statelessness. Request bodies containing
resume,session_id, or any other unknown field are rejected with 422. Runs are hermetic: CLI session persistence is disabled, so no resumable transcript is written, and host and project settings are not loaded (setting_sourcesis empty), so hooks or MCP servers from those settings cannot leak into a run. Auto memory is disabled (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1), and MCP configuration is strict and isolated. Managed policy settings and~/.claude.jsonstill load. The default system prompt is the Claude Code preset. What still persists after a run: files the agent creates or edits in the workspace, and ordinary CLI bookkeeping under~/.claude.
Development
Requirements: Python 3.11–3.14 and uv.
git clone https://github.com/dceoy/casapi.git
cd casapi
uv sync
uv run uvicorn casapi.main:app --host 127.0.0.1 --port 8000
Swagger UI is at http://127.0.0.1:8000/docs.
uv run ruff format --check .
uv run ruff check .
uv run pyright .
uv run pytest
uv run mkdocs build --strict
Dependency versions are tracked in the committed uv.lock.
License
AGPL-3.0-only. See LICENSE.
Metadata
Release files for casapi 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| casapi-0.1.0.tar.gz | 26.0 kB | With provenance | Details for casapi-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| casapi-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for casapi-0.1.0-py3-none-any.whl |
Total release size: 52.1 kB
Release files / casapi-0.1.0.tar.gz
| Download URL | casapi-0.1.0.tar.gz |
|---|---|
| Size | 26.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f50aa82d405f5f0ff5cfb70b9a5215d5fed458f84d41b66e75b9af2145483afa
|
|
BLAKE2b-256 checksum How to use checksums |
65b5609a127da7353efee8458205d0baf08c2b62f5fb61fe5e0d7950a223d384
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / casapi-0.1.0-py3-none-any.whl
| Download URL | casapi-0.1.0-py3-none-any.whl |
|---|---|
| Size | 26.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
167877423f384b4ec972c1b1707980bb768edf01247716e4a71e45bebd9a8b1b
|
|
BLAKE2b-256 checksum How to use checksums |
22f73023386c7f2a42e0f460e1a0d85c107c36189ae4df99469d1a05debd37bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for casapi 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for casapi-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.