Run locally

1. Initialize local state

The default state directory is ~/.dataporch:

dataporch secrets init

This creates the owner-only master key and encrypted secret store. The connection-definition and MCP-token stores are created when those features first write state; the runtime MCP credential is created only while the runtime is running. Installation, help, version, and status commands do not initialize state.

The default paths are:

~/.dataporch/admin.sock
~/.dataporch/mcp.sock
~/.dataporch/master.key
~/.dataporch/secrets.store
~/.dataporch/connections.store
~/.dataporch/mcp-token.json
~/.dataporch/mcp-control-token
~/.dataporch/logs/

If you built from a checkout, replace dataporch with ./bin/dataporch in the examples.

2. Run in the foreground

Foreground mode is the right choice for a terminal, container, CI job, or external supervisor:

dataporch run -f

It keeps the process attached to the current terminal, handles termination signals, and does not create a native service definition.

3. Run as a per-user service

dataporch run
dataporch status

dataporch run registers and starts the native user service, waits for /healthz, and is safe to repeat when the service is already healthy. macOS uses launchd; Linux uses systemd --user. DataPorch does not enable startup at login.

dataporch status reports the state, PID, configured address, and native log location when the service is running. On macOS, logs are under ~/.dataporch/logs/; on Linux, use the reported journalctl --user-unit dataporch.service command.

The default address is 127.0.0.1:8080. Verify the process is listening:

curl --fail http://127.0.0.1:8080/healthz

Expected response:

{"status":"ok"}

The direct HTTP MCP endpoint is http://127.0.0.1:8080/mcp. It requires the bearer token created with mcp-token create; health checks do not.

Bundled agent plugins use the local stdio adapter instead:

dataporch mcp

The adapter forwards MCP messages through ~/.dataporch/mcp.sock and reads an owner-only credential from ~/.dataporch/mcp-control-token. The runtime creates that credential for its current lifetime and removes it on shutdown. The command requires an already running runtime and does not start one.

Upgrade, restart, and stop

After installing a new binary, refresh the registered service:

go install github.com/adamraziv/dataporch/cmd/dataporch@v0.1.0
dataporch restart

restart refreshes the service definition using the currently invoked executable and configuration. stop stops and unregisters only the generated service definition while preserving state:

dataporch stop

Keys, stores, connections, tokens, and logs remain on disk. There is no dataporch start command; use dataporch run. There is also no dataporch run --foreground alias; use dataporch run -f.

Use explicit paths

For system services, containers, or a deliberately managed layout, set every state path explicitly. Each path must be absolute, non-empty, and distinct:

export DATAPORCH_ADMIN_SOCKET_PATH=/run/dataporch/admin.sock
export DATAPORCH_MCP_SOCKET_PATH=/run/dataporch/mcp.sock
export DATAPORCH_MASTER_KEY_PATH=/etc/dataporch/master.key
export DATAPORCH_SECRETS_STORE_PATH=/var/lib/dataporch/secrets.store
export DATAPORCH_CONNECTIONS_STORE_PATH=/var/lib/dataporch/connections.store
export DATAPORCH_MCP_TOKEN_STORE_PATH=/var/lib/dataporch/mcp-token.json
export DATAPORCH_MCP_CONTROL_TOKEN_PATH=/var/lib/dataporch/mcp-control-token
dataporch run -f

Keep the boundary local

Do not bind to a non-loopback address just to make a local agent work. Use dataporch mcp for bundled local plugins. If a deployment must be remote, add a real transport boundary—TLS, authentication, network policy, and operational controls—before exposing the direct HTTP bearer token.