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; files and state are 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.

## 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.
- Shared: the server runs at most 8 requests at a time across everyone,
  including Alex's other work, so responses slow down when it's busy.
- 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.

### 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 (survives suspend/resume)
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.