Daemion docs

How do I create a job?

~5 minutes
Prerequisites: Running gateway

Jobs are autonomous work units that run on a schedule or on demand. You create them by chatting with Daemion — no config files to write by hand.

Create a job by chatting

Tell Daemion what you want the job to do. It handles the schema, prompt, and scheduling.

text

You: Create a job that checks server health every hour and writes a report to workspace/health/

Daemion: I’ll create a server-health job with an hourly cron trigger. What endpoint should I ping, and should I alert you if anything looks off?

Daemion creates a job extension in SQLite. The job is live immediately — no restart required.

What the job schema looks like

Every job conforms to the JobSchema defined in src/schema/job.ts. The key fields:

yaml

name: server-health # lowercase, hyphens only description: ‘Check server health every hour’ enabled: true

trigger: type: cron schedule: ‘0 * * * *’ # hourly

agent: haiku # haiku | sonnet | opus, or a named agent

context:

  • read: HEARTBEAT.md # inject a file into context
  • engram: ‘recent failures’ # semantic recall from Engram

outputs:

  • file: workspace/health/ # write result to disk
  • engram: true # store in Engram knowledge graph

priority: normal # low | normal | high | urgent max_duration: 120 # seconds

Trigger types: cron (schedule string), manual (run on demand only), or chain (fires after another job succeeds).

Verify with a dry run

Before letting the job fire on schedule, confirm the engine can resolve it:

POST /run/:job Auth required

Run a job immediately. Pass ?dry=true to resolve the job without invoking the agent — confirms the job name, agent, and schedule are valid.

Parameter Type Description
job REQUIRED string (path) Job name as registered. URL-encode spaces.
dry boolean (query) Set to true for a dry run — no agent invocation, no cost.
bash

Dry run — verifies job resolves without calling the agent

curl -X POST “http://localhost:3001/run/server-health?dry=true”
-H “Authorization: Bearer $DAEMION_TOKEN”

Full run — calls the agent immediately regardless of schedule

curl -X POST http://localhost:3001/run/server-health
-H “Authorization: Bearer $DAEMION_TOKEN”

A successful dry run returns:

json

{ “job”: “server-health”, “dry”: true, “result”: “[dry run] Job “server-health” resolved successfully (agent: haiku)”, “costUsd”: 0, “durationMs”: 0 }

Check the schedule

Ask Daemion to confirm when the job will next fire:

text

You: When does server-health next run?

Daemion: server-health is scheduled hourly (0 * * * *). Next fire: 14:00 UTC.

Common questions

Q Can I use a named agent instead of haiku/sonnet/opus?
Yes. Set agent to the name of any agent extension registered in the gateway. Daemion resolves disk agents first, then falls back to extension agents in SQLite.
Q How do I chain jobs together?
Add a chains list to the parent job: chains: [report-send]. The chained job runs automatically after the parent succeeds. The chained job's own trigger is ignored.
Q How do I disable a job without deleting it?
Toggle it off: POST /extensions/:id/toggle with enabled: false. Or ask Daemion to disable it.
Q What does max_duration do?
The engine enforces this as an invocation timeout (in seconds). Jobs that exceed it are stopped and marked failed. Default is 300 seconds.
Q Where do job outputs go?
File outputs write to the path under workspace/ relative to the project root. Engram outputs are stored in the knowledge graph and available for recall in future jobs.

What can go wrong

Job run errors

404 {"error": "job not found"} — The job name doesn’t match any registered job. Names are case-insensitive but must match exactly (hyphens, no spaces). Run GET /extensions?type=job to see all registered jobs.

400 {"error": "agent not found"} — The agent field references an agent that isn’t registered. Use haiku, sonnet, opus, or the name of an installed agent extension.

403 {"error": "unauthorized"} — Missing or invalid bearer token. Set $DAEMION_TOKEN from ~/.daemion/.gateway-token.

What’s next?