Forge Fleet quickstarts

Each section ends with Verify steps you can run from the same shell (adjust host/port).

Default ports: 18765 (CLI default), 18766 (common user install). Replace $BASE and $TOKEN below.

export BASE=http://127.0.0.1:18765
curl_auth=( )
[[ -n "${FLEET_TOKEN:-}" ]] && curl_auth=( -H "Authorization: Bearer ${FLEET_TOKEN}" )

1. Local developer (5–10 min)

1. Prefer the guided Install & run locally page (venv + Compose recap); then pip install -e . via Git install if you need packaging detail.
2. Run fleet-server --host 127.0.0.1 --port 18765 with a writable FLEET_DATA_DIR, or use your install’s systemctl --user unit.
3. Open /admin/ if the bind is loopback.

Verify

curl -sS "${BASE}/v1/version" | head -c 400; echo
curl -sS "${curl_auth[@]}" "${BASE}/v1/health" | head -c 400; echo

Expect 200 and JSON. If you set FLEET_BEARER_TOKEN and bind beyond loopback, include Authorization.

2. Fresh host operator (20–45 min)

1. Follow HOST-BOOTSTRAP.md for Docker/OS and (optional) Caddy.
2. Install Fleet per GIT-INSTALL.md; set FLEET_BEARER_TOKEN in forge-fleet.env for non-loopback binds.
3. systemctl --user enable --now forge-fleet.service (or your distro equivalent).

Verify

curl -sS "${curl_auth[@]}" "${BASE}/v1/version"
curl -sS "${curl_auth[@]}" "${BASE}/v1/health"
curl -sS "${curl_auth[@]}" "${BASE}/v1/admin/snapshot" | head -c 600; echo

Expect 200 for all three. /v1/admin/snapshot is large—pipe to head or jq filters.

3. First API job (after server is up)

Requires Docker available to the Fleet process. See EXAMPLES.md for a full docker run example.

Verify

# After POST /v1/jobs returns {"id":"..."}:
curl -sS "${curl_auth[@]}" "${BASE}/v1/jobs/<job_id>"

Expect status to move from queued → running → terminal state.

4. Workspace upload job (longer)

1. POST /v1/jobs with meta.workspace_upload_required: true and optional manifest flags — WORKSPACE_UPLOAD.md.
2. PUT /v1/jobs/{id}/workspace with gzip tarball.
3. Poll GET /v1/jobs/{id}.

Verify: job meta.workspace_state progresses to ready; then runner starts the container.

5. Container template build (Docker host)

1. Ensure requirement_templates.json and Docker/BuildKit per CONTAINER-TEMPLATES.md.
2. POST /v1/container-templates/build with requirement ids.

Verify

curl -sS "${curl_auth[@]}" "${BASE}/v1/container-templates/status"

6. Caddy / TLS front (20–60 min)

Follow CADDY-SYSTEMD.md or CADDY-UNIFIED-GRANITE.md. DNS + certificates dominate wall time.

Verify: curl https://your-host/v1/health with correct Authorization when bearer is required.

7. Remote git self-update (maintainer)

From a machine that can reach the API: POST /v1/admin/git-self-update with bearer — see API-REFERENCE.md and README.md. System installs under /opt/forge-fleet may return 400 with a host-shell command instead.

Verify: GET /v1/version shows updated package_semver / git metadata after restart.

Common failures

More: Troubleshooting.