# 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 an agent there (pi or Claude Code),
using a local Qwen 3.8 27B model. No API keys needed.

## 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-1
  # Claude Code: code.proc.io/ax/ax-task-runner:claude-vllm-3
  image: code.proc.io/ax/ax-task-runner:pi-vllm-1
  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"'
#   (Claude Code image: claude -p "...")
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.

## 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.