raft / docs
Guides

Keep a service across resumes

You can save a service configuration on disk so it starts a fresh process after resume. You cannot preserve running process memory. Use a persistent box you own; stopping a disposable box deletes it and its snapshots.

Manage the deadline

TTL is 60 to 2,592,000 seconds. For ordinary creation and resume, it starts after launch completes, using the host clock. The creation default is 600 seconds unless your controller changes it. There is no expiry-off option; activity and detached jobs do not renew it.

raft list --location lab
raft extend "$box" --ttl 7200

Set $box to your running handle before extending it. list exposes the Unix deadline as string stopAt, or "" when absent. extend resets it to host time plus TTL; it does not add to the previous deadline. For a stopped box, use raft resume "$box" --ttl 7200 instead.

The host checks every 15 seconds. Outages, graceful shutdown and long operations such as backups can delay enforcement. raft gc --location lab checks immediately and may stop or delete other expired boxes on that host too.

Persistent boxes retain disk on stop or expiry, but host retention can later delete them. Check raft config --location lab and each stopped box's deleteAt. Use backup before that deadline. Forks default to persistent; recovered boxes are persistent. Controller defaults can change ordinary creation behavior.

Enable a service

This example serves /workspace as the image's developer user. Use a running persistent box and ensure that user's files are readable. Replace ExecStart and the working directory for your application:

raft exec "$box" -- bash -lc 'cat > /etc/systemd/system/workspace-web.service <<"UNIT"
[Unit]
Description=Workspace HTTP example
After=network.target

[Service]
User=developer
WorkingDirectory=/workspace
ExecStart=/usr/bin/python3 -m http.server 8080 --bind 0.0.0.0
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
UNIT
systemctl daemon-reload
systemctl enable --now workspace-web.service'
raft exec "$box" -- systemctl status workspace-web.service --no-pager

Open raft forward "$box" --remote 8080 --local 8080, then visit http://127.0.0.1:8080. Ctrl+C closes the tunnel, not the service.

Stopping ends current requests and every guest process. When an interruption is acceptable:

raft stop "$box"
raft resume "$box" --ttl 3600
raft exec "$box" -- systemctl is-active workspace-web.service

Wait for guest startup if the check runs too early, then reopen the tunnel. If the service fails, inspect raft exec "$box" -- journalctl -u workspace-web -n 30 --no-pager.

A fork or snapshot copy inherits the enabled service and any secrets on disk, so it starts its own process. Disable the example with raft exec "$box" -- systemctl disable --now workspace-web.service. See background jobs for one-off commands and host policies for retention and previewed cleanup.

On this page