Inspecting Dream Status

Inspecting Dream Status

When to use

• "Is Dream up?"
• "What port is the Dream gateway on?"
• "Find the substrate URL"
• tau commands fail with cloud-related errors despite Dream being started
• dream reports universe \xxx` does not exist`

Core commands

All dream status subcommands take the universe as a positional argument. There is also a --universe / -u / --to flag (defaults to blackhole), but for clarity prefer the positional form.

dream status universe   <universe>   # overall universe state + service ports
dream status gateway    <universe>   # HTTP gateway endpoint (used to hit functions)
dream status substrate  <universe>   # substrate (build/runtime) endpoint

Replace <universe> with whatever the multiverse was started with — typically:

• default if started via dream start
• blackhole if started via dream new multiverse without --universes

Quick readiness check

dream status universe default

A successful call lists the running services and their assigned ports. If it errors with universe \` does not exist`, the universe name is wrong — see the table below.

Finding the gateway port (for curl tests)

# `dream status gateway` often prints a blank line before `@ http://...`; awk '/@ http/{print $3}' can be empty.
GW=$(dream status gateway default | grep -Eo 'http://[0-9.]+:[0-9]+' | head -n1)
echo "$GW"
# example: http://127.0.0.1:<gateway_port>

Combine with a domain FQDN to hit an HTTP function:

FQDN=$(awk '/^fqdn:/{print $2; exit}' config/domains/<domain>.yaml)
curl -i -H "Host: $FQDN" "$GW/<path>"

Dream local is plain HTTP on the gateway port from dream status gateway … (often http://127.0.0.1:<port>) — not https:// on :443 unless you intentionally terminate TLS elsewhere. If the browser or curl shows connection refused on 80/443, you're usually missing the explicit gateway port.

Universe-name failure mode

dream status always prints results for exactly the universe name passed in. Common mismatches:

Recovery: re-check how Dream was started, then call dream status universe <correct_name>. See starting-dream-locally.

Status output (what to look for)

dream status universe <u> typically shows:

• A list of services (auth, seer, tns, patrick, monkey, substrate, gateway, ...) each with assigned host:port.
• Lifetime / uptime info per service.

dream status gateway <u> shows the inbound HTTP endpoint clients use; pair with the Host: header to route to a specific FQDN.

dream status substrate <u> shows the substrate HTTP endpoint; useful when you need to talk to substrate APIs directly (rare in normal flows).

Gotchas

• Gateway URL parsing: dream status gateway <u> often prints a blank line before @ http://.... Parsers like awk '/@ http/{print $3}' can return empty; prefer grep -Eo 'http://[0-9.]+:[0-9]+' | head -n1 (same pattern as verifying-taubyte-functions).
• The default value of the --universe / -u flag is blackhole, even on builds where dream start defaults to default. Pass the universe explicitly to avoid silent mismatches.
• A status call that hangs usually means the multiverse process exited; check the terminal running dream start / dream new multiverse --daemon.
• Ports are dynamic per run. Don't hard-code ports across sessions — re-discover via dream status each time.

Related skills

• starting-dream-locally — bring up Dream and pick a universe name
• triggering-dream-builds — uses the same universe argument
• verifying-taubyte-functions — uses the gateway port + Host header to hit a function
• diagnosing-dream-builds — uses the discovered ports for direct jobs API calls