DockSplit Agent

DockSplit Agent is the local runtime that connects a machine to DockSplit, listens for profile/service events, and executes Docker Compose operations on that machine.

The npm package exposes two binaries:

• docksplit: CLI entry point for normal usage.
• docksplitd: daemon entry point for service managers.

Install

Use one install path:

npm i -g @docker-digital/dockernet-agent

Verify:

docksplit --help

First Run

Run in foreground for the first setup:

docksplit up --foreground

This keeps logs attached to the terminal while the agent prepares runtime, registers the machine, connects Tailscale, subscribes to realtime events, and starts local services.

Useful variants:

docksplit up --fast
docksplit up --verbose
docksplit up --foreground --verbose

Background Runtime

Run in the background:

docksplit run --daemon

Run in the foreground:

docksplit run

Enable the lightweight local HTTP API:

docksplit run --daemon --service 3333

Equivalent port flag:

docksplit run --daemon --port 3333

OS Service

Install and start as an OS service:

docksplit install-daemon

Supported service managers:

• macOS: launchd
• Linux: user systemd

Uninstall the OS service:

docksplit uninstall-daemon

Stop

Stop the running daemon:

docksplit down

Alias:

docksplit stop

Listen Mode

Observe realtime events without executing them:

docksplit listen

Use a custom event file:

docksplit listen --file ~/.dockernet-agent/recent-events.json

Use a specific machine key:

docksplit listen --machine-key <machine_key>

Commands

| Command | Description | | --- | --- | | docksplit up --foreground | Start and keep the current CLI process attached. | | docksplit up --fast | Start with reduced startup logs. | | docksplit up --verbose | Start with full startup logs. | | docksplit run | Run agent runtime in foreground mode. | | docksplit run --daemon | Run agent runtime detached from the terminal. | | docksplit run --daemon --service 3333 | Run detached with local HTTP API enabled. | | docksplit install-daemon | Register and start as OS service. | | docksplit down | Stop the running daemon. | | docksplit stop | Alias for down. | | docksplit listen | Observe realtime events without executing them. | | docksplit uninstall-daemon | Stop and unregister OS service. | | docksplit --help | Show CLI help. |

Runtime Files

| Path | Description | | --- | --- | | ~/.dockernet-agent/config | Local agent configuration. | | ~/.dockernet-agent/agent.pid | Daemon PID file. | | ~/.dockernet-agent/docksplit.sock | Local control socket. | | ~/.dockernet-agent/log/ | Agent logs. | | ~/.dockernet-agent/profiles/ | Profile working directories. | | ~/.dockernet-agent/recent-events.json | Recent realtime events used by listen. |

Development

Install dependencies from the monorepo root:

yarn install

Run the CLI locally:

npm run start:cli -- up --foreground

Run the daemon entry locally:

npm run start:daemon

Build:

npm run build

Run tests:

npm test

Troubleshooting

docksplit: command not found

Reinstall globally:

npm i -g huynhthuc/docksplit

Check npm global bin path:

npm bin -g

Docker Permission Denied

Make sure Docker is running and the current user can access Docker.

On Linux:

sudo usermod -aG docker "$USER"

Log out and log back in after changing Docker group membership.

Agent Cannot Reach DockSplit API

Check DNS/network:

curl -I https://api-backend.docksplit.cloud

Then run with verbose foreground logs:

docksplit up --foreground --verbose