Troubleshooting and FAQ
Start with af doctor
Section titled “Start with af doctor”af doctor --jsonIt checks that the private network is up, your certificate is valid, the platform answers, your clock is right, and that this device reaches your Lane’s addresses (lane-network). Every check is ok, warn or fail, and healthy is true when nothing failed.
Troubleshooting
Section titled “Troubleshooting”lane-network fails, or SSH to a Box hangs
Section titled “lane-network fails, or SSH to a Box hangs”This device is not accepting the routes to your Lane. On Linux run sudo tailscale set --accept-routes; on other systems, check that Tailscale is connected and signed in with the email your admin invited. lane-network is a warn, not a failure, when no Box is running.
UNREACHABLE
Section titled “UNREACHABLE”The private network or the platform is down. Run af doctor --json. If Tailscale is up and it still fails, tell your admin, and use your fallback (for CI, a GitHub-hosted runner) meanwhile.
Your certificate is missing, expired or revoked. Ask your admin for a new one-time token, then run af login.
NO_KEYS when creating a Box
Section titled “NO_KEYS when creating a Box”Your Lane has no SSH key yet: af keys add ~/.ssh/id_ed25519.pub, then repeat the create.
SSH says permission denied
Section titled “SSH says permission denied”Check that the key you use is in af keys list --json, and that the Box shows it: af box show <name> --json lists the fingerprints it accepts. A Box whose key update failed gets the current keys after af box stop and af box start.
My Runner’s jobs stay queued
Section titled “My Runner’s jobs stay queued”The labels in runs-on must all be on the runner. A JIT-registered Runner has only the labels you named, so include self-hosted. Check af runner list --json for registered and busy, and af runner logs <name> --json.
HOST_FULL
Section titled “HOST_FULL”The platform has no room right now. Wait retryAfterSeconds once, try a smaller size, or try later. Do not loop.
Can my coding agent use this?
Section titled “Can my coding agent use this?”Yes, that is what af is for. See Using af with your coding agent.
Who can see my machines?
Section titled “Who can see my machines?”Only you, from your own devices. Other people on the platform cannot see or reach your Lane, and isolation is audited. Your admin runs the platform.
Are my Boxes backed up?
Section titled “Are my Boxes backed up?”Every Box is snapshotted nightly, with 7 days kept, and you can take snapshots yourself. Snapshots stay on the platform, so keep important work in git and pushed somewhere else.
Can I open a port to the internet?
Section titled “Can I open a port to the internet?”No. Machines are reachable only over the private network, from your devices. They can reach the internet themselves.
Does af store my GitHub token?
Section titled “Does af store my GitHub token?”No. Registration and removal tokens go in on stdin, are used once, and are never stored.
How do I update af?
Section titled “How do I update af?”Your admin sends a new link and checksum. Install it the same way as the first time (Getting started). af version shows your version and the contract version it speaks.
I need more RAM, disk or cores.
Section titled “I need more RAM, disk or cores.”Ask your admin: every cap can be raised.