edgeplaned Daemon

edgeplaned is the headless work-executor daemon. Think of edgeplane as kubectl and edgeplaned as kubelet — edgeplane is the operator interface, edgeplaned is the node-side executor. Agents communicate with it via Unix socket; operators interact through edgeplane agent commands, not edgeplaned directly.

Responsibilities

edgeplaned absorbed these daemon responsibilities across v0.8–v0.10:

Version	Responsibility
v0.8–v0.9	Fleet agent lifecycle (launch, restart, Zellij integration via ZellijHosted runtime)
v0.9	Cron dispatch — ~/.edgeplane/edgeplaned/cron.toml, 1-minute tick loop
v0.10	Watchdog — polls systemd units, restarts dead agents with throttling
v0.15+	Task worker — ephemeral subagent spawning for mesh execution

Starting edgeplaned

For normal operation, use edgeplane daemon up. For advanced scripting or debugging, invoke edgeplaned directly:

edgeplane daemon up

# Advanced / debug
edgeplaned run --backend-url http://localhost:8008

edgeplaned reads its node identity from /etc/edgeplane/node.json at startup. Register the node first:

edgeplane agent node register --hostname <hostname>
# → writes JWT to /etc/edgeplane/node.json

For persistent operation, run as a systemd user service:

[Unit]
Description=EdgePlane Daemon
After=network-online.target

[Service]
ExecStart=/usr/local/bin/edgeplaned run --backend-url http://localhost:8008
Restart=on-failure
RestartSec=5
EnvironmentFile=%h/.edgeplane/env

[Install]
WantedBy=default.target

Agent Runtimes

edgeplaned supports these agent runtime kinds (see crates/edgeplaned/crates/edgeplaned-runtimes/src/):

Runtime	Description
claude_code	One-shot claude -p
claude_agent_acp	Persistent JSON-RPC; ACP protocol
codex	OpenAI Codex CLI
gemini	Google Gemini CLI
zellij_hosted	Long-running agents hosted in a Zellij pane; signals via edgeplane agent signal

Unix Sockets

All sockets live in ~/.edgeplane/edgeplaned/:

Socket	Purpose
mgmt.sock	JSON-RPC 2.0 management gateway
secrets.sock	Secrets broker (agent subprocesses only)
edgeplaned.sock	PTY attach gateway

Federated Attach

As of v0.13.x, edgeplaned supports mediated attach — the tower proxies WebSocket attach requests to the node daemon, eliminating the need for direct network access to agent nodes.

When the web dashboard or edgeplane attach connects to an agent on a remote node:

Web browser → /api/attach-ws → edgeplane-tower → edgeplaned (remote node) → agent PTY

The attach-secret handshake is self-healing — if edgeplaned restarts, it re-registers and re-issues the attach secret. The next attach attempt succeeds automatically.

Secrets Broker

edgeplaned injects two environment variables into agent subprocesses:

• EP_SECRETS_SOCKET — path to secrets.sock
• EP_SECRETS_SESSION — session ID for this agent

Agents retrieve secrets without ever receiving raw credentials:

VALUE=$(edgeplaned get-secret MY_API_KEY)

Or speak the protocol directly:

echo '{"op":"get","session":"'$EP_SECRETS_SESSION'","name":"MY_API_KEY"}' \
  | nc -U "$EP_SECRETS_SOCKET"

Raw secret values are never written to disk or embedded in config files.

Cron Scheduling

Jobs are defined in ~/.edgeplane/edgeplaned/cron.toml. edgeplaned reads it at startup and on edgeplane agent cron reload.

Cron job (exact timing)

[[job]]
name     = "my-job"
schedule = "30 6 * * 1-5"   # 5-field cron, local time
session  = "my-profile"      # target profile / Zellij session name
prompt   = "run /my-skill"
# dispatch = "signal"        # "signal" (default) or "bash"

Heartbeat job (approximate cadence)

[[job]]
name     = "my-heartbeat"
kind     = "heartbeat"
interval = "30m"             # "Ns", "Nm", "Nh", "Nd", or compound "2h30m"
session  = "my-profile"
prompt   = "run /my-check"

Dispatch modes:

dispatch	Behavior
signal (default)	edgeplane agent signal to the profile agent — has full profile context
bash	Literal shell command passed to bash -c — no LLM, no session

Manage cron:

edgeplane agent cron list              # list all jobs and next fire time
edgeplane agent cron describe <name>   # full config + last fire
edgeplane agent cron history <name>    # recent fires
edgeplane agent cron reload            # re-parse cron.toml (no daemon restart needed)
edgeplane agent cron gc-now            # force garbage-collect stale dedup entries

Cron schedules are local time. Dispatcher tick is on the order of minutes — sub-minute expressions and sub-minute heartbeat intervals won’t fire faster than the tick.

Watchdog (Agent Supervision)

edgeplaned polls each supervised agent’s systemd unit every 60 seconds. Dead units are restarted with throttling (90s post-restart grace, 30-minute retry throttle) plus an optional nightly restart.

edgeplane agent supervise list
edgeplane agent supervise status <id>
edgeplane agent supervise restart <id>
edgeplane agent supervise pause <id>    # disable auto-restart
edgeplane agent supervise resume <id>   # re-enable auto-restart

Task Worker

edgeplaned’s task worker runs the claim loop that enables distributed mesh execution. See Architecture: Ephemeral Task Agents for the full model.

Running an agent work loop:

edgeplane daemon agent enroll --domain <id> --runtime claude_code
edgeplane run claude --domain <id>

Environment variables for the work loop:

Variable	Default	Purpose
EP_BASE_URL	http://localhost:8008	Backend URL

Creating a MeshTask for dispatch:

The /work/missions/$MISSION_ID/tasks REST path is an internal API path. The agent-facing interface is via MCP tools — prefer submit_mesh_task from within an agent session and claim_mesh_task for claiming. The curl example below is for direct API access (e.g. from automation scripts or debugging):

curl -X POST http://<edgeplane-host>/work/missions/$MISSION_ID/tasks \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "task title",
    "description": "what to do",
    "claim_policy": "first_claim",
    "priority": 5
  }'

Claim policy options:

Policy	Behavior
first_claim	Any available agent with matching capabilities
assigned	Specific agent only
broadcast	All agents

Retry a failed task (internal REST path — prefer the retry_mesh_task MCP tool from agent sessions):

curl -X POST http://<edgeplane-host>/work/tasks/<task-id>/retry \
  -H "Authorization: Bearer <session-token>"

Known Limitations

• Event bus threading: task_ready WebSocket events may not wake the work loop reliably in single-worker deployments. The startup poll is the reliable dispatch path — restart the loop after creating tasks if events don’t fire.
• sudo in tasks: agent subprocesses run without a TTY; sudo will fail unless the node has passwordless sudo configured.
• GLIBC mismatch: build edgeplane/edgeplaned natively on the target node if it runs an older glibc than your build machine.
• Tasks vs MeshTasks: the regular task API (/domains/{id}/m/{id}/t) is Kanban-style tracking. The work loop only operates on MeshTask objects at /work/missions/{id}/tasks. Always use the /work/ API when creating tasks for agent dispatch.

See Also

• Architecture: Ephemeral Task Agents — distributed subagent model
• Reference: CLI — full edgeplane command surface including edgeplane agent cron and edgeplane agent supervise