Harness quickstart
In this quickstart you run the moca harness on your own machine, without root. It starts these services:
- the supervisor and its pool of warm workers, where the agent runs;
- the sandbox relay;
- one sandbox container, where the agent's commands run;
- Redis, where sessions are stored.
Then you send the agent a turn, resume the session, and stream a reply.
Trial, not production. The Docker Compose path is a trial by design and will not be promoted to Stable. When you are ready to deploy, see Deploy and operate.
Before you start​
You need:
- Docker (or podman's
dockerCLI) with Compose (docker composeordocker-compose); curl;- a model credential. This page uses an Anthropic API key.
1. Start the harness​
curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/deploy/compose/install.sh \
| ANTHROPIC_API_KEY=sk-ant-... sh
The installer does four things:
- It fetches
docker-compose.ymlinto~/.serverless-harness. To use another directory, setSH_COMPOSE_DIR. - Once, it writes
~/.serverless-harness/.env(mode 0600) with the relay tokens it generates and the model variables from your shell. A re-run never overwrites this file. - It pulls the images. If it can't reach the registry, it starts nothing.
- It runs
docker compose up -d.
The data plane listens on http://127.0.0.1:8080. Redis and the relay aren't published to your
host.
By default it accepts unauthenticated calls (SH_REQUIRE_AUTH=false), so a plain curl works.
Adding the control plane for mocactl does not close that: the operator's model credential still
serves an unauthenticated curl /turn unless you set SH_REQUIRE_AUTH=true in .env. What changes
is that a present but invalid token is refused.
2. Send a turn​
curl -s -H 'Content-Type: application/json' \
-d '{"prompt":"Remember the word pineapple, then run uname -a and tell me the kernel."}' \
http://127.0.0.1:8080/turn
The reply is JSON with response, stopReason, usage and sessionId. The uname command ran
in the sandbox container, not in the worker that runs the agent. This split is moca's
"brain and hands". Copy the sessionId.
3. Resume the session​
The session's history is stored in Redis, so a new request with the same id continues it:
curl -s -H 'Content-Type: application/json' \
-d '{"sessionId":"<the id>","prompt":"What word did I ask you to remember?"}' \
http://127.0.0.1:8080/turn
If you name a session that doesn't exist, the call returns 404 session_not_found. To start a new
session, omit sessionId.
4. Stream a turn​
Ask for server-sent events:
curl -N -H 'Content-Type: application/json' -H 'Accept: text/event-stream' \
-d '{"sessionId":"<the id>","prompt":"Count to five slowly."}' \
http://127.0.0.1:8080/turn
You get these frames:
event: textframes, each with adelta;tool_useandtool_resultframes when the agent runs a command;- a final
event: done.
5. Watch it, then stop it​
cd ~/.serverless-harness && docker compose logs -f # watch it
cd ~/.serverless-harness && docker compose down # stop it
Redis keeps sessions on the moca-redis named volume, with AOF on. docker compose down followed
by up keeps your sessions. docker compose down -v removes the volumes and starts clean.
Optional: use mocactl instead of curl​
mocactl talks to the harness through its control plane, which adds GitHub login and
per-user sessions and credentials. To add the control plane to this trial:
- Create a GitHub OAuth app with Enable Device Flow ticked. It doesn't need a client secret.
- Re-run the installer with the app's client ID:
curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/deploy/compose/install.sh \
| SH_GITHUB_CLIENT_ID=Ov23li... sh
mocactl --control-plane-url http://127.0.0.1:8090 login
mocactl --control-plane-url http://127.0.0.1:8090 doctor
mocactl --control-plane-url http://127.0.0.1:8090 run "hello"
The control plane is the only URL you give mocactl. It advertises the harness through
GET /v1/discovery.
When you first log in, mocactl asks for your own inference credential. The harness sends that
credential to the model endpoint as Authorization: Bearer, so it must be a gateway token or
another token that the endpoint accepts as a Bearer token. To install mocactl itself, see
Get started.
What you just did​
- A supervisor handed your HTTP connection to a warm worker: no cold start.
- The worker ran the agent loop and stored the session in Redis.
- The agent's command went through the relay to a remote sandbox.
The same processes run on a single VM and on Kubernetes. Only the process manager and the isolation differ.
Next​
- Do more: Set up mocactl against the Compose trial, Use mocactl, dispatch over the HTTP API.
- Understand: Sessions and turns, Session multiplexing.
- Look up: HTTP API, mocactl.