A Dorkyfile

A Dorkyfile is one machine's declared state, written in TOML. It is usually named <name>.dorky.toml and kept beside the code and files the machine uses.

The file is the durable user interface to the machine. You can read it, version it, review a change, and apply the same declaration again. dorky apply provisions the machine when it is absent and converges an existing machine to the file. Reapplying an unchanged file is a no-op.

The six questions

A Dorkyfile describes the parts of a machine that are under declarative control today. The last row is part of the design, with no working configuration surface yet.

Question	Declaration	Status
Where does the machine run?	[provider].substrate selects fly, unikraft, or sprite.	Built
Which base image does it use?	[image].ref selects the immutable runtime image.	Built
Which packages are available?	Top-level packages and nixpkgs describe the shared command-line environment.	Built
Which services run?	Each [[service]] declares a process or a static service.	Built
What can the machine expose and reach?	Service routes describe inbound paths. Upstream records describe where agent turns can run. A telemetry endpoint can receive spans.	Built; fine-grained service capability claims are designed
How is it priced or funded?	Pricing, funders, and commerce claims have no public Dorkyfile stanza.	Designed, not built

The smallest useful declaration can be short:

name = "hello"

[provider]
substrate = "fly"

[[service]]
name = "greeter"

[service.routes]
"/" = { mode = "public", respond = { body = "hello\n", status = 200 } }

This declares a machine named hello with one static service and one public response. A service can instead run a process, ship files, declare packages, and expose gated routes. See Dorkyfile services for those forms.

Configuration, secrets, and keys

The Dorkyfile contains configuration and reference names. Secret values and issued keys are stored separately.

A service can list the secret names it needs:

[[service]]
name = "worker"
run = "bun ${DORKY_SERVICE_DIR}/worker.js"
port = 8080
secrets = ["API_TOKEN"]

An upstream uses creds_ref in the same way: the value is the name of a stored secret, such as OPENAI_API_KEY. Set a value through standard input with dorky secret set <machine> NAME. The machine stores it at 0600, and the value is never echoed or written into the Dorkyfile.

Routes declare how a caller is admitted: for example, public, token, or owner. Keys are issued, listed, and revoked with dorky keys. The Dorkyfile contains route modes and secret references, but no credential values.

Preview, compare, and apply

Three commands cover the declaration loop:

dorky apply hello.dorky.toml --plan
dorky diff hello hello.dorky.toml
dorky apply hello.dorky.toml

--plan reads the declaration and its referenced files locally, then prints the ship manifest without contacting or changing a machine. dorky diff compares a running machine with the file through a dry run; it reports which configuration planes would change without applying them. The final command converges the machine.

Convergence is two-way. Removing a Dorkyfile-managed route or upstream retracts it on the next apply. An unchanged plane stays untouched.

There are two user-visible apply speeds:

• Configuration — services, routes, upstreams, secret references, telemetry, and packages apply live. Package changes can take longer to fetch and switch, but do not reboot the machine.
• Image — changing [image].ref is the reboot boundary.

The provider choice is made when the machine is provisioned. An existing machine cannot switch substrates in place because its durable storage belongs to that substrate.

Reserved and designed surfaces

These names may appear in internal records or parser errors. They are not available as working declarations:

Surface	Current status
[env]	Reserved for environment variables. dorky apply rejects it today.
[[spec]]	Parsed as an AgentSpec reference, but not applied to the machine.
Inline secret:NAME references	Designed. Use declared secret names and dorky secret set today.
Per-service capability claims	Designed. Current routes use the built route modes.
Pricing and funders	Designed, with no public Dorkyfile schema.

For the first complete apply, continue with Getting started.