Troubleshooting

Something not working? Find the problem below and work through the steps in order, most likely fix first.

Start here: dorkos doctor

Before anything else, run:

dorkos doctor

It checks your whole setup (Node version, data directory, port, agent tools, login and tunnel config) and reports what's wrong in plain words. It reads and probes; it never changes anything. If the doctor finds the problem, its report tells you the fix. If everything passes and something is still off, keep reading.

"DorkOS won't start, something about a port"

You'll see an error like Port 4242 is already in use. DorkOS listens on port 4242 by default (the address your browser uses to reach it), and something else on your machine already has that port claimed.

1. Start DorkOS on a different port instead: dorkos --port 8081 (or any free port).
2. Find out what's using port 4242, so you can decide whether to stop it: lsof -i :4242. This lists the process holding that port.
3. Make the new port stick so you don't have to type it every time: dorkos config set server.port 8081.

In the desktop app this usually fixes itself. 4242 is a starting guess, so when something else has it the app takes the next free port (4243, then 4244) and Settings → Server shows the address it landed on. It only stops if ten ports in a row are unavailable, and the message names the range.

A port you chose is treated differently. If you pinned one with dorkos config set server.port or the DORKOS_PORT environment variable, the app will not move off it. It stops and tells you the port is taken, because anything you already pointed at that port would break if DorkOS quietly answered somewhere else. Free the port and open the app again, or pin a different one.

"I opened the desktop app and it says another DorkOS is already running"

You have dorkos running in a terminal, and both it and the app want the same DorkOS folder (~/.dork). One folder, one server: two would write over each other's sessions and agents.

Quit the one in your terminal (Ctrl+C), then open the app again. If you'd rather keep both, start the terminal one against a folder of its own: DORK_HOME=~/.dork-cli dorkos.

"I closed the DorkOS window but it's still running"

That's on purpose. The desktop app keeps running when you close its window, so any agents you left working carry on. It tells you this the first time you close the window, once.

Look for the DorkOS icon in the menu bar on macOS, or in the notification area next to the clock on Windows. Click it to open the window again, see how many agents are working, or quit. Closing the window is not quitting, so if you want DorkOS gone, quit from that icon, from the app menu, or with Cmd+Q on macOS.

"Restart Server and Reset All Data don't work in the desktop app"

Both buttons in Settings → Advanced now refuse in the desktop app, and say why. The app starts and stops the server itself, so a restart triggered from inside would leave you with no server running at all.

• To restart: quit DorkOS and open it again. That does the same thing.
• To start over: quit DorkOS, delete your data folder (~/.dork), then open DorkOS again and it will set itself up from scratch. Nothing is deleted while the button is refusing, so a refusal never means you lost anything.

Neither restriction applies when you run DorkOS from the CLI or Docker.

"It says my agent isn't ready" or "Claude Code / Codex / OpenCode won't connect"

DorkOS checks two things for each agent tool: is the CLI installed, and are you logged in. When either is missing, DorkOS shows a Connect button instead of trying to run a session and failing partway through.

1. Open Settings > Runtimes to see which agent tool needs attention. Each one shows Ready or Connect, plus an Advanced section with the exact command to run.
2. Install and log in to the tool that's missing:
   • Claude Code: DorkOS bundles the Claude Code engine, so there's nothing to install. You only need to authenticate: set your ANTHROPIC_API_KEY, or log in with a claude CLI if you have one on your PATH.
   • Codex: npm i -g @openai/codex && codex login
   • OpenCode: npm i -g opencode-ai && opencode auth login
3. Click Refresh in the Runtimes tab (or click Connect again). DorkOS re-checks the CLI and login state and flips to Ready once both pass.

"Is the server even running?"

DorkOS exposes a health check you can hit directly, no login required:

curl http://localhost:4242/api/health

Swap in your own address if DorkOS isn't on 4242. Settings → Server always shows it.

A healthy server answers with something like:

{ "status": "ok", "version": "0.45.1", "uptime": 182.4 }

If that command fails to connect at all, the server process isn't running, or it's running on a different port than you expect (see the port section above).

"My agent or project isn't showing up"

This is almost always Mesh, DorkOS's discovery system, not having scanned the right folder yet. Discovery only runs when you ask it to, it doesn't watch your filesystem in the background.

1. Open the Mesh tab and click Scan for Agents. This looks for marker files (CLAUDE.md, AGENTS.md, a .dork/agent.json file, and others) in the folders DorkOS already knows about.
2. Check that your project is actually inside a folder DorkOS scans. By default that's DorkOS's working directory. If your project lives elsewhere, add its folder to the mesh.scanRoots list in ~/.dork/config.json — run dorkos config edit to open the file, and put the paths in the list: "mesh": { "scanRoots": ["/home/user/projects"] }.
3. Confirm the project has one of the marker files Mesh looks for (a CLAUDE.md, an AGENTS.md, or a .dork/agent.json). No marker, no match.
4. If you approved or denied the project before, it won't show up as a new candidate again, check the Mesh tab's existing list rather than expecting it to reappear.

See Agent Discovery for the full list of what Mesh looks for and how scanning works.

"My chat seems stuck" or "the agent isn't responding"

1. Give it a moment. Long tool calls (installing packages, running tests, a big refactor) can look idle even though the agent is still working.
2. Check the Live updates indicator in the status bar. It only appears when live updates aren't healthy, so no indicator is good news. If it says Reconnecting, DorkOS is recovering automatically and nothing is lost, just wait. If it says Live updates lost, refresh the page; if that doesn't help, confirm the DorkOS server itself is still running (see the health check above). On a narrow window that same warning reads Offline.
3. If the agent has genuinely gone silent (no output at all, not even a tool call) for 10 minutes, DorkOS interrupts the turn on its own and shows an error message in the chat saying so. You don't need to do anything, just send a new message to try again.
4. Open the session in a fresh browser tab. If it opens fine there, the problem was the original tab, not the session itself.
5. Still stuck? Check the server logs for anything unusual: they print to your terminal while DorkOS is running, and also get written to ~/.dork/logs/dorkos.log.

"I can't reach DorkOS from my phone or another computer"

By default DorkOS only listens on your own machine (localhost), so other devices can't see it yet. You have two options for opening it up safely: a temporary public link, or a proper reverse proxy for something more permanent. See Tunnel Setup and Reverse Proxy.

"My file upload was rejected"

DorkOS enforces upload limits so one runaway attachment can't fill your disk: a max file size (10 MB by default), a max number of files per upload (10 by default), and optionally a list of allowed file types (any type, by default).

1. If the error mentions a file being too large, either shrink the file or raise the limit: dorkos config set uploads.maxFileSize 52428800 (that example sets it to 50 MB).
2. If the error mentions too many files at once, either upload fewer at a time or raise the limit: dorkos config set uploads.maxFiles 20.
3. If the error says a file type isn't allowed, someone has restricted uploads.allowedTypes in your config. Check ~/.dork/config.json, or ask whoever administers your DorkOS instance.

Frequently asked questions

Is DorkOS free? Yes. It's free and open source (MIT licensed). See the DorkOS Documentation home page for the full picture.

Does my code leave my machine? DorkOS itself runs entirely on your machine and doesn't send your code anywhere. The agent tools it drives (Claude Code, Codex, OpenCode) do call out to their own AI provider to do their work, that's how they think, the same as if you ran them yourself from a terminal.

Can I run more than one agent at once? Yes, running several agents across several projects at once is the whole point of DorkOS. See Sessions and Agent Discovery.

How do I update DorkOS? Depends how you installed it, npm, Docker, or from source each update a little differently. See Installation > Updating.

How do I uninstall DorkOS? Run dorkos cleanup to remove it and its data. See Uninstall for the full walkthrough, including Docker and manual cleanup.

How do I report a bug or request a feature? Run dorkos feedback in your terminal, or use "Report an issue" inside DorkOS. Either one opens a prefilled GitHub issue with your version, operating system, and settings already filled in. You review and edit everything before you submit; DorkOS sends nothing on its own.