Initial guide

2026-10-08 15:23:52 -07:00
commit 2b7df6d6a6
2 changed files with 133 additions and 0 deletions
@@ -0,0 +1,107 @@
+# 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.