guide/README.md

# Running agents on proc-0 (for friends)

You get gVisor-sandboxed coding agents running on Alex's server. Each task
clones a git repo into a sandbox and runs a coding agent there, backed by a
Qwen 3.8 27B model that Alex hosts. No API keys or accounts needed. The
recommended agent is [pi](https://pi.dev); see [Using pi with
Qwen](#5-using-pi-with-qwen). Claude Code is available too.

## 1. Join

1. Install [Tailscale](https://tailscale.com/download) and sign in with any
   account.
2. Accept the two machine shares Alex sends you: **`ax`** and **`ax-router`**.
   They show up in your Tailscale machine list.
3. Check you can reach them: `tailscale ping ax.tailb55c1.ts.net`

## 2. Install the `ax` CLI

Pick your platform: `darwin-arm64` (Apple Silicon), `darwin-amd64`,
`linux-amd64` or `linux-arm64`.

```bash
P=darwin-arm64
B=https://code.proc.io/api/packages/ax/generic/ax-cli/ac23328-proc.3
curl -fLO $B/ax-$P && curl -fLO $B/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing
chmod +x ax-$P && sudo mv ax-$P /usr/local/bin/ax
```

This is a patched build of [google/ax](https://github.com/google/ax). Upstream's
`go install` won't work here.

## 3. Point it at the server

Add to your shell profile:

```bash
export AX_SERVER=ax.tailb55c1.ts.net:8080
export AX_ROUTER=ax-router.tailb55c1.ts.net:80
```

`ax get tasks` should print a (possibly empty) table.

## 4. Run a task

Grab [`task.yaml`](task.yaml) from this repo
(`curl -fLO https://code.proc.io/ax/guide/raw/branch/main/task.yaml`). Rename
the task and workspace with your own prefix (e.g. `sam-`), since everyone
shares one namespace and names must be unique, and point it at your repo:

```yaml
apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: sam-myrepo
  atespace: default
spec:
  git:
    - name: origin
      repo: "https://github.com/you/your-repo.git"   # public repos only
      branch: "main"
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: sam-hello
  atespace: default
spec:
  # pi:          code.proc.io/ax/ax-task-runner:pi-vllm-3
  # Claude Code: code.proc.io/ax/ax-task-runner:claude-vllm-3
  image: code.proc.io/ax/ax-task-runner:pi-vllm-3
  workspaces:
    - name: sam-myrepo
      path: /workspace
  debug: true          # required for `ax ssh`
```

```bash
ax apply -f task.yaml            # creates it, suspended
ax resume task sam-hello         # starts it; the first start can take a minute,
                                 # so re-run if it times out
ax ssh sam-hello -- ls /workspace  # the repo is cloned into /workspace/<repo-name>
ax ssh sam-hello -- sh -c 'cd /workspace/your-repo && pi -p "explain the build system"'
ax suspend task sam-hello        # frees the worker; /workspace is kept
ax resume task sam-hello         # picks up where it left off
ax delete task sam-hello         # when done
```

`ax ssh` runs one command and streams its output. It doesn't forward your
keyboard, so there's no interactive shell or agent TUI. Run agents headless
(`pi -p` / `claude -p`); each call can pick up files earlier ones left in the
workspace.

Tasks are immutable: to change one, delete it and apply again.

Suspend saves only `/workspace`. It isn't a RAM snapshot: resume starts a fresh
container with your `/workspace` restored, and everything outside it resets.

## 5. Using pi with Qwen

### The model

- **Qwen 3.8 27B** (`qwen3.8-27b`), served by vLLM on proc-0's GPU. It supports
  tool calling and reasoning ("thinking").
- 128K-token context (131,072). Large repos still need the agent to read
  selectively, which it does by default.
- One RTX A6000, shared by everyone including Alex's other work. The weights
  are FP8, with an FP8 KV cache, prefix caching and MTP speculative decoding.
- From inside a sandbox it's also a plain OpenAI-compatible API at
  `http://vllm.vllm.svc:8000/v1`, if you want to script against it directly.
  It isn't reachable from your own machine. Read the live settings with
  `curl -s http://vllm.vllm.svc:8000/metrics | grep config_info`. They're
  read-only: changing them restarts the server for everyone.

### Performance: one long request at a time is best

Decode reads all ~29 GB of weights per token, so concurrent requests share the
GPU's memory bandwidth. Long prompts also prefill in chunks that stall the
other stream. Per-stream decode speed from the server's benchmark:

| Prompt size | 1 request | 2 at once (each) |
|---|---|---|
| 1k tokens | 40 tok/s | 33 tok/s |
| 16k | 35 | 22 |
| 64k | 39 | 6 |
| 120k | 44 | 2 |

pi transcripts grow every turn, so two busy agents slow each other down a lot.
When the server is busy (or for unrelated questions), start fresh with
`--no-session` instead of `-c`, and keep context small.

### pi is preconfigured

The pi image (`ax-task-runner:pi-vllm-3`) points pi at that model, so there's
nothing to log in to or set up. pi runs in the task's working directory with
four tools: `read`, `bash`, `edit` and `write`. It can run builds and tests and
change files in the repo.

Since `ax ssh` isn't interactive, always use print mode (`-p`). Wrap commands
in `sh -c '…'` so `cd` and pipes run inside the sandbox:

```bash
T=sam-hello R=/workspace/your-repo

# one-shot question or task
ax ssh $T -- sh -c "cd $R && pi -p 'find where config is loaded and explain it'"

# keep going in the same conversation (a session file in /workspace/.pi, so it survives suspend)
ax ssh $T -- sh -c "cd $R && pi -p -c 'now add a test for the env-var override'"

# feed it input
ax ssh $T -- sh -c "cd $R && git diff | pi -p 'review this change'"

# read-only: no edits, no shell
ax ssh $T -- sh -c "cd $R && pi -p --tools read,grep,find,ls 'audit error handling'"

# a fresh conversation that isn't saved
ax ssh $T -- sh -c "cd $R && pi -p --no-session 'list the TODOs'"

# see what it changed
ax ssh $T -- sh -c "cd $R && git status && git diff"
```

### Thinking level

Qwen thinks before answering. More thinking is slower but better on hard
problems. pi defaults to `medium`. Change it per call with `--thinking`:

| `--thinking` | Use for |
|---|---|
| `off` | quick lookups, renames, boilerplate |
| `low` | simple edits |
| `medium` (default) | most work |
| `high` | tricky bugs, design questions (Qwen's maximum; slowest) |

`minimal` and `xhigh` aren't supported by this model, and pi rounds them to the
nearest supported level.

### Tips

- Put project instructions in an `AGENTS.md` at your repo root. pi reads it
  automatically (build commands, conventions, what not to touch).
- The workspace is yours for the task's lifetime: run `npm install`, builds and
  tests freely. Package downloads work from npm, PyPI and GitHub.
- To get work out, have pi produce a patch (`git diff > /workspace/out.patch`)
  and `ax ssh $T -- cat /workspace/out.patch > out.patch` it to your machine.
  Pushing from the sandbox would need credentials, and nothing there is private.
- Long runs are tied to your `ax ssh` connection. Break big jobs into steps
  and use `pi -p -c` to continue between them.

### Claude Code instead

Set the image to `code.proc.io/ax/ax-task-runner:claude-vllm-3` and use
`claude -p "…"` (also against Qwen). In our tests, pi was faster on the same
model. Claude Code's `--continue` history doesn't survive a suspend; pi's does.

## Ground rules and limits

- **Two tasks can run at once, server-wide.** Suspend yours when you're not
  using it. Suspended tasks cost nothing.
- **Network is allowlisted.** Sandboxes can reach the model, GitHub, npm and
  PyPI over HTTPS, and nothing else. Ask Alex if you need more.
- **Nothing is private between users.** Anyone with access can see, `ax ssh`
  into, or delete any task. Don't put secrets in tasks, env vars or repos you
  clone here.
- The model is shared with Alex's other work, so expect it to be slower when
  busy.
- `ax ssh` or `ax resume` sometimes fails on the first try. Running it again
  usually works.