Diffinery

codician/diffinerypublic

Open-source, agent-first GitHub and GitHub Actions alternative that runs on your own Cloudflare account: git hosting, pull requests, code review and drop-in GitHub Actions YAML on Workers, Durable Objects, R2 and Containers.

Docs: terminal task troubleshooting, jobs API runner and placementTries, account data on the docs home (#153)

Terminals get a troubleshooting table for the jail (#146): refused hosts,
Go modules, a jail that can't start, signing in again, Codex API keys,
and say which registries can't be published to. The jobs API reference
names runner and placementTries (#150). The docs home links account
export and deletion (#152).


Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL

Co-authored-by: Claude <noreply@anthropic.com>
Canberk Demirci authored · GitHub committed signed1 parent 1afc28ecommit 9552cd2b761f66817b55de9d8c6b23da14a8539dBrowse files
3 files changed+16−2
modifiedapps/diffinery/docs/agents/terminal.md+13−0View file
@@ -79,6 +79,8 @@
7979 | Maven Central | `repo1.maven.org`, `repo.maven.apache.org` |
8080 | apt | `deb.debian.org`, `security.debian.org`, `archive.ubuntu.com`, `security.ubuntu.com` (also plain HTTP, downloads only) |
8181
82+The registries are there for downloads. PyPI and crates.io publish through other hosts (`upload.pypi.org`, `crates.io`), so a task can't publish there; npm and RubyGems take uploads on the same hosts they serve downloads from (see the risks below).
83+
8284 Anything else is refused, and the refusal shows in the task's transcript. Go modules aren't reachable, because the Go module proxy fetches any address it's given. Vendor them (`go mod vendor`) or run Go tasks in a [sandbox of their own](/docs/agents/tasks). Codex signed in with an API key instead of ChatGPT needs `api.openai.com`, which isn't on the list, so use a ChatGPT sign-in.
8385
8486 If the sandbox can't start the jail, the task fails and nothing runs.
@@ -128,6 +130,17 @@
128130
129131 What you type and what the shell prints go only between your browser and the sandbox. Diffinery keeps no copy and doesn't log it: the recent output that redraws the screen lives in the sandbox's memory and is gone when the terminal ends. The [audit log](/docs/security/audit-log) records only that a terminal was opened or ended, by whom, in which repository, with which agent and branch and the Claude Code and Codex versions its buttons install, and that you accepted the notice (`terminal.terms`, `terminal.open`, `terminal.task`, `terminal.end`).
130132
133+## Troubleshooting
134+
135+| What you see | Cause and fix |
136+| --- | --- |
137+| No **Give it a task** box, or `the terminal was opened without agent tasks` | The terminal was opened without **Will run agent tasks**. End it and open another with the box ticked. |
138+| `diffinery: refused a connection to <host>:443 from the task (only the hosts in /docs/agents/terminal#what-a-task-can-reach)` in the transcript | The agent or a tool it ran tried a host outside the [list](#what-a-task-can-reach). Work that needs other hosts belongs in a task with a [sandbox of its own](/docs/agents/tasks), or in the terminal itself, outside a task. |
139+| `go: ... dial tcp ...` or another Go module download error | Go modules aren't reachable from a terminal task. Commit them with `go mod vendor`, or run the task in a sandbox of its own. |
140+| The task fails with "The task's jail couldn't start in this terminal's sandbox, so nothing ran." | bubblewrap couldn't start in the sandbox; the transcript has its error. Nothing ran and nothing was pushed. End the terminal, open a new one and run the task again. |
141+| The terminal's Claude Code or Codex asks you to sign in again after a task | The CLI refreshed its sign-in inside the task, on its private copy, and the provider retired the old refresh token. Sign in again in the terminal. |
142+| Codex fails to reach `api.openai.com` in a task | Codex is signed in with an API key, and only ChatGPT sign-ins work in terminal tasks. Run `codex login` with your ChatGPT plan, or use a task with a sandbox of its own. |
143+
131144 ## For administrators
132145
133146 Terminals are on by default. Set the Worker variable `TERMINALS` to `off` to switch them off: nobody can open one, and the ones that are open end within a minute. See [Configuration](/docs/self-hosting/configuration#worker-variables).
modifiedapps/diffinery/docs/index.md+1−0View file
@@ -20,6 +20,7 @@
2020 | See what needs you and what your agents did since yesterday | [Today](/docs/agents/today) |
2121 | Have one of your agents review pull requests for bugs, like Bugbot | [Agent review](/docs/agents/review) |
2222 | Script against Diffinery | [REST API guide](/docs/reference/rest-api), [REST API reference](/docs/api) and [CLI reference](/docs/reference/cli) |
23+| Export your data or delete your account | [Exporting and deleting your account](/docs/accounts/account-data) |
2324 | Run your own instance | [Deploy Diffinery](/docs/self-hosting/deploy) |
2425 | Report a security problem | [Reporting a vulnerability](/docs/security/disclosure) |
2526
modifiedapps/diffinery/src/docs/api-meta.ts+2−2View file
@@ -1295,7 +1295,7 @@
12951295 description: "A zip with one text file per job. Jobs past 24 MB of logs in total are left out.",
12961296 access: "read",
12971297 },
1298- "GET /repos/{owner}/{repo}/actions/runs/{id}/jobs": { summary: "List a run's jobs", access: "read" },
1298+ "GET /repos/{owner}/{repo}/actions/runs/{id}/jobs": { summary: "List a run's jobs", description: "Each job as `GET .../actions/jobs/{id}` returns it, with `runner` and `placementTries`.", access: "read" },
12991299 "GET /repos/{owner}/{repo}/actions/runs/{id}/pending_deployments": {
13001300 summary: "List the environments a run waits on",
13011301 description: "Environments whose required reviewers or wait timer hold the run's jobs, with `current_user_can_approve` for the caller. See [Required reviewers and wait timers](/docs/actions/environments#required-reviewers-and-wait-timers).",
@@ -1329,7 +1329,7 @@
13291329 status: 201,
13301330 body: { enable_debug_logging: ["boolean", "Accepted and ignored."] },
13311331 },
1332- "GET /repos/{owner}/{repo}/actions/jobs/{id}": { summary: "Get a job", description: "The job with its steps.", access: "read" },
1332+ "GET /repos/{owner}/{repo}/actions/jobs/{id}": { summary: "Get a job", description: "The job with its steps. GitHub's job fields, plus Diffinery's own: `runner` (the hosted container's `image`, `location` and `instance`; `null` on a self-hosted runner) and `placementTries` (how many times a hosted job went back in line before a runner took it: no free container, or a runner on a replaced image). See /docs/actions/runners.", access: "read" },
13331333 "POST /repos/{owner}/{repo}/actions/jobs/{id}/rerun": {
13341334 summary: "Re-run a job",
13351335 description: