Skip to content

Align the Smolmachines backend with its lifecycle and exec docs - #1422

Draft
ReganBell wants to merge 1 commit into
mainfrom
sandbox/smolmachines-docs-alignment
Draft

ReganBell wants to merge 1 commit into
mainfrom
sandbox/smolmachines-docs-alignment

Conversation

@ReganBell

Copy link
Copy Markdown
Contributor

Aligns the Smolmachines backend with the Smolmachines documentation.

  • Poll readiness until the ready flag is true and fail immediately with the reported reason when the machine enters the error state.
  • Enforce the egress proxy with allowCidrs and hosts when SMOLMACHINES_EGRESS_PROXY_URL is set; network is create-time only, so a resident machine created open fails closed with a destroy instruction.
  • Request base64 output and decode the byte-exact stdoutB64 and stderrB64 fields instead of the truncating text fields and spool files.
  • Give ephemeral machines a TTL and send autoStopSeconds from SMOLMACHINES_AUTOSTOP_SEC.
  • Wire the shared S3 home snapshot path behind SMOLMACHINES_SNAPSHOT_S3_BUCKET, since stopping is documented as not a backup.
  • State the OS and idle behaviour truthfully in the profile and fill the resource spec.

Docs: https://smolmachines.com/docs/cloud/api-reference https://smolmachines.com/docs/cloud/lifecycle-storage-networking https://smolmachines.com/docs/guides/agent-sandboxes-ci

Needs live QA before merge.

Readiness: poll GET /v1/machines/{id} until ready is true and stop on
state error with the provider's reason, instead of treating started as
usable (api-reference "Readiness and lifecycle", lifecycle guide).

Output: request ?output=b64 and decode stdoutB64/stderrB64, which the
API documents as byte-exact and untruncated, dropping the in-guest
spool files and the 1 MiB text cap workaround. A control plane without
the byte streams still fails closed on a truncated text field.

Egress: with SMOLMACHINES_EGRESS_PROXY_URL set, machines are created
with network.mode allowCidrs and hosts limited to the proxy, the profile
claims domain enforcement, and an existing machine created open fails
closed rather than running with only the proxy env. Without the knob
machines stay open and config warns, as for sprites.

Lifecycle: scratch machines carry ttlSeconds so a crashed core cannot
leave them running; SMOLMACHINES_AUTOSTOP_SEC sends autoStopSeconds on
create and the profile only claims idle stop when it is configured. The
unused exec stdin field is gone.

Recovery: SMOLMACHINES_SNAPSHOT_S3_BUCKET and _INTERVAL_SEC wire the
shared home tar snapshot at teardown, hydrate a replacement machine from
it, expose persistHomeSnapshot and status recovery, and record failures.
Bookkeeping lives in the artifact store. The export endpoint is a
whole-disk registry artifact with no documented restore contract, so it
was not used.

Profile: the OS line names the configured image instead of an
unverified distribution, and cpus/memoryMb fall back to the documented
4 vCPU / 8192 MB defaults.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant