Troubleshooting

Most problems are with the engine, the background service that runs the lab. The app runs it as a LaunchAgent called com.ownpaas.engine, so it keeps running when the window is closed.

Where to look first

• Settings › Engine shows whether the engine runs and has Start, Stop and Restart.
• The engine’s log is ~/Library/Logs/ownpaas/engine.log. The last lines usually say what went wrong.
• In a terminal:

tail -n 50 ~/Library/Logs/ownpaas/engine.log
launchctl print gui/$(id -u)/com.ownpaas.engine | head -n 30

The engine does not start

macOS has not allowed the LaunchAgent. Open System Settings › General › Login Items and allow ownpaas under “Allow in the Background”. Then choose Start in Settings › Engine.

It started once and stopped. Restart it from Settings › Engine, or in a terminal:

launchctl kickstart -k gui/$(id -u)/com.ownpaas.engine

If it stops again, the log names the cause; the two most common are below.

A port is taken. The engine needs three ports (by default 18580 and 18581 over TCP, 18582 over UDP). The log then says address already in use. Find the process:

lsof -nP -iTCP:18580 -sTCP:LISTEN
lsof -nP -iUDP:18582

Stop that process, or move the lab to other ports: Settings › Engine › Edit Configuration… › API and Ports. The three ports move together, and the app updates its own connection; agents need to be added again (Add MCP server to…) to pick up the new port.

The configuration does not load. If you edited ownpaas.yaml by hand, the log names the line. The app keeps the last five versions next to it as ownpaas.yaml.bak-<date>; copy one back, or open Edit Configuration…, which checks every change before saving.

Another lab on the same Mac

All labs on a Mac share the VM network 192.168.64.0/24. Two labs running at the same time can give two VMs the same address. Run one lab at a time, or stop the other one’s engine first. The first-start sheet lists engines of other labs it finds.

The agent does not see the ownpaas tools

• Start a new agent session; agents load MCP servers at the start.
• Claude Desktop reads its configuration only at launch: quit it and open it again.
• Check that the entry exists: claude mcp list for Claude Code, ~/.cursor/mcp.json for Cursor, ~/.codex/config.toml for Codex.
• After the lab moved to other ports, add the MCP server again.

The Keychain asks for permission again and again

The app keeps its tokens in the login Keychain. macOS asks again when the app’s signature changed, for example after an update that was not signed the same way. Choose Always Allow.

Servers do not start, or are slow

Every running VM reserves its memory on your Mac. Overview shows how much of the Mac’s CPUs, memory and disk the lab has allocated. Stop servers you do not need, or use smaller server types.

Still stuck

Write to the address on the About page with the last 50 lines of engine.log and what you did before the problem appeared.