sandcastle check prints one line per item, each starting with a mark. It exits with 1 when any
line is FAIL, and with 0 otherwise.
Mark Means
okthe item is as it should be FAILthe item keeps the installation from working; fix it warnsomething to know; it fails nothing
The lines come in the order of the sections below. Without a keep that answers, check stops
after the images: everything after them is asked through the keep. Without a configuration it can
read, it stops after the configuration. The lines about the units, the networks and the gate are
printed only on a machine where sandcastle install wrote the units.
In the lines, <…> stands for a value: a name, an address, a number.
Line What to do
ok keep: ready— FAIL keep: the keep does not answer at <socket>; start it with sandcastle keepsee Troubleshoot FAIL keep: XDG_RUNTIME_DIR is not set to a folder; the keep's socket lives thererun check in your own session, as the operator FAIL keep: <reason>the keep answered, but not as it should; see journalctl --user -u sandcastle-keep
Line What to do
FAIL config: <file>: <key and rule>fix the file; the line names the key. The rules are in config.yaml
The files are read here. What they ask of the toolbox is checked later .
Line What to do
ok keep and gate: run as their units define— FAIL <piece>: the container sandcastle-<piece> does not exist; run sandcastle installsandcastle installFAIL <piece>: the container is <state>, not runningsystemctl --user restart sandcastle.target, then read its journalFAIL keep: runs as "<user>", not as the operator (<uid>)sandcastle installFAIL gate: runs as the operator (<uid>); it must notsandcastle installwarn <piece>: the container was not started with "<flag>", as its unit saysa drop-in removed a lock; remove the drop-in warn <piece>: the container was started with <flag>a drop-in added a port, a capability or a namespace of the machine; remove it warn <piece>: the container publishes portsthe same warn <piece>: the container has capabilities <list>the same warn <piece>: the container's disk is writablethe same FAIL <piece>: the container lost the networks <list>; restart it with systemctl --user restart sandcastle-<piece>restart it as the line says. A podman network reload that fails leaves it so; see Troubleshoot warn <piece>: the container is on the networks <list>, not <list>the same as a published port: a drop-in added a network warn keep: the container has DNS settings; its unit says DNS=nonethe same warn <piece>: runs <image>, not this binary's build <build>; restart it with systemctl --user restart sandcastle-<piece>restart it as the line says FAIL link: the network sandcastle-link does not exist; run sandcastle installsandcastle installFAIL link: the network sandcastle-link is <range>, but its unit says <range>; run sandcastle install --link <range>run it as the line says ok gate: its way out has the routes of the second barrier— FAIL gate: the network sandcastle-egress is not what the installation needs: <how>systemctl --user restart sandcastle-gate, which makes the network anewFAIL gate: the network sandcastle-egress cannot be read: <reason>the same ok gate: its list is the configuration's— warn gate: the list it runs is not the configuration's; restart it with systemctl --user restart sandcastle-gaterestart it as the line says FAIL gate: its files cannot be read at <folder>: <reason>systemctl --user restart sandcastle-gateFAIL gate: the ACL has <n> rule(s) besides the defaultthe same; the gate writes its list anew when it starts FAIL gate: <reason>the same
The networks and their routes are in Network names and ranges .
One pair of lines for each destination with internal:, every time. See
Reach a service inside your network .
Line What to do
warn <source or capability> <name>: internal exception: the gate lets <ip:port> through for <name>a reminder that the exception is open warn <source or capability> <name>: http:// is outside the promise: nothing encrypts the way to <ip:port>use https:// if the service can FAIL <source or capability> <name>: internal <ip:port> is in the keep-gate network or the gate's way out, which is never openedchoose an address outside the installation’s ranges
What the configuration asks of the toolbox, then each capability’s box limits and image.
Line What to do
FAIL config: capability claude: destination and model are requiredadd them to capabilities.claude FAIL config: capability claude: effort "<value>" is not one of low, medium, high, xhigh, maxfix effort FAIL config: capability claude: max_tokens must be at least 1fix max_tokens FAIL config: capability ocr: reaches nothing outside its box; remove destinationremove the block FAIL config: capability <name>: sandcastle has no such capabilityonly claude and ocr exist FAIL config: source <name>: the name "<name>" is a capability's; give the source another namerename the source FAIL config: source <name>: the capability "<name>" is not enabled in config.yamlenable it, or take it out of the source’s capabilities warn capability <name>: box.<limit> <value> is above the default <value>a limit above its default is outside the promise; lower it if you can FAIL capability <name>: the image sandcastle-<name>:<build> of this build is missing; run sandcastle installsandcastle installFAIL capability ocr: the image has the languages "<languages>" and the configuration "<languages>"; run sandcastle installsandcastle installFAIL capability <name>: podman cannot be run: <reason>install Podman, or put it on PATH FAIL capability <name>: podman cannot look at the image <image>: <reason>see what podman image inspect says
Line What to do
ok source <name>: reachable, <n> waiting— FAIL keep: <reason>the keep could not say which secrets it can use; see its journal FAIL source <name>: secret <secret>: missing; run sandcastle secret set <secret>run it as the line says FAIL source <name>: secret <secret>: <rule>the secret’s file breaks a rule; see Manage secrets FAIL source <name>: the keep does not know this destination; restart the keep after changing the configurationsystemctl --user restart sandcastle.targetFAIL source <name>: the token was rejected; create a new worker token and set it with sandcastle secret set <secret>run it as the line says FAIL source <name>: <reason>the source could not be asked: the line says what the keep, the gate or the source answered. See Troubleshoot
Line What to do
ok capability <name>: usable— FAIL capability claude: secret claude: <rule>as for a source’s secret FAIL capability claude: the Claude API rejected the key (<what it said>); create a key in the runner's workspace and set it with sandcastle secret setsee claude FAIL capability claude: the model "<model>" does not exist for this keyfix model in config.yaml FAIL capability claude: the Claude API answered <status>: <what it said>read what it said FAIL capability claude: <reason>the API could not be reached; the line says why FAIL capability ocr: tesseract has no language data for "<language>"; install itsandcastle install, which builds the image with the configured languagesFAIL capability <name>: <reason>the box did not answer the check; the line says how
Last, for each destination the gate refused in the last hour, the likeliest cause.
Line What to do
warn gate: refused <name> <n> time(s) in the last hour, last at <time> (<reason>): the name resolves to the internal network; if that is meant, give the destination an internal: ip:portsee Troubleshoot warn gate: refused <name> <n> time(s) in the last hour, last at <time> (<reason>): the name is not on the gate's list; restart the gate after changing the configurationthe same warn gate: refused <name> <n> time(s) in the last hour, last at <time> (<reason>): see the gate's logjournalctl --user -u sandcastle-gate