Skip to main content

Worked examples

Each example below is a whole task: what you say, what the assistant does step by step, and what you end up with. The tool names are what you will see in your client's output. Your assistant may word things differently or take an extra step to check something — that is normal.

All of these need a Pro account except 8. Add a laptop to the VPN, which works on Free too.

1. From an idea to a running app​

"I want to build a small notes app that my study group can use. I've never used this platform. Where do I start?"

What the assistant does

  1. plan_my_build — gets the ordered list of decisions for a new build. It deploys nothing.
  2. whoami, list_labs — sees your plan and what you already have.
  3. Asks you who will use the app. Your study group means it needs a public address, so a domain is in scope.
  4. Asks you whether notes must be kept between visits. Yes — so a database is in scope. It calls list_services and shows you the database engines your platform offers. You choose one.
  5. Shows you the labs you can deploy and lets you pick one to build in.
  6. Walks through the domain, the database user, the routing, and the startup script — before the first deploy, so nothing you set up by hand is lost when the lab is rebuilt.
  7. deploy_lab, then wait_for_deploy — deploys once, with everything in place, and waits until it is really running.

What you get: a lab, a database and a plan you chose step by step, and a first deploy that does not need to be redone. From here, the assistant can write the code with you — see Workspace and files.

Let it ask you questions

The planning helper is built to make the assistant show you real options and let you choose. If you would rather it decided, say so — it will tell you what it would pick and why, and confirm before acting.

2. Deploy a lab and connect​

"Deploy my Essentials lab and give me the SSH command."

What the assistant does

  1. list_labs — finds your Essentials lab and its id, and whether it is already running.
  2. deploy_lab — queues the deploy. If the lab already existed, this rebuilds it; the assistant mentions that only your home directory is kept.
  3. wait_for_deploy — waits, typically a minute or two, until the deploy reports deployed.
  4. lab_info — reads the lab's address, username and password.

What you get: a running lab and a ready-to-paste command such as ssh <username>@<your-lab-ip>, plus the web editor link if the lab has one. To use the lab's private address you need to be on the VPN — see example 8 and Connect to a lab.

3. Publish a site on a domain with HTTPS​

"My site in the Essentials lab serves on port 80. Put it online at bakery.selfmade.one."

What the assistant does

  1. list_domains — checks whether you already hold the name and whether it is verified.
  2. add_domain — registers bakery.selfmade.one if you do not have it.
  3. lab_info — reads the lab's current domains, so none are dropped.
  4. configure_lab_routing with the site made public, sending your existing domains plus the new one, and asking for the change to be applied — which saves and redeploys in one step.
  5. wait_for_deploy — waits for the redeploy.
  6. list_ssl_certificates — confirms a certificate is issued, or reports that it is on its way.

What you get: the site at https://bakery.selfmade.one. A new certificate can take a few minutes to appear after the first deploy.

For a port other than 80 — an app on 3000, say — the assistant adds an HTTPS proxy for that port instead. For a domain you own, point its DNS A record at the platform first. See Domains and Publish ports.

Saving is not applying

Routing changes land on the next deploy. If you ask only to "save" the domain, nothing changes until the lab is redeployed — which looks exactly like the domain being broken.

4. Run a dev server and check it serves​

"Start the dev server in my notes-app project and check it's actually working."

What the assistant does

  1. open_workspace — pins your lab and the notes-app folder, and reads its git state.
  2. read_lab_file on package.json — finds the dev command and the port.
  3. run_command — installs dependencies (npm install), which finishes and returns.
  4. start_lab_process — starts npm run dev as a background process named web. run_command would not do: a server started that way stops when the command ends.
  5. lab_probe on the port, retrying for a few seconds until it answers — one web request from inside the lab.
  6. If the probe fails: lab_process_logs to read what the server printed.

What you get: a running dev server and proof it answers — for example "200 OK, served the login page". The server is only visible inside the lab. To open it in your browser, ask:

"Make it reachable at notes.selfmade.one."

and the assistant adds an HTTPS proxy for the port and applies it, as in example 3.

It will not survive a redeploy by itself

A redeploy stops background processes. To have the server start every time, ask the assistant to add the command to the lab's startup script.

5. Add a database and connect from the lab​

"Create a PostgreSQL database for my notes app and connect the app to it."

What the assistant does

  1. list_services — sees what you already have and how many service users you have left.
  2. Asks you for a username and a password — nothing generates one. It checks them against the rules: username 5–16 letters, digits or underscores; password 8–64 characters with no apostrophe.
  3. add_service_user — creates the user on PostgreSQL.
  4. create_database with the name notes — you get <username>_notes.
  5. edit_lab_file — puts the connection details in your app's settings file (in your home directory, so they survive a redeploy).
  6. run_command — runs the app's migration or a quick connection test.

What you get: a database the app can reach from inside the lab. The connection host, port and details for each engine are in MySQL, MariaDB and PostgreSQL.

Keep the password somewhere you control

Only MongoDB passwords can be read back through the assistant. For other engines, the password is shown on the web dashboard — save it when you choose it.

6. Fix a failed deploy​

"My Ubuntu lab won't come up. What's wrong?"

What the assistant does

  1. list_labs, then lab_status — confirms the lab is in failed.
  2. lab_logs — reads the deploy log. The real reason is there: a line from the startup script, a missing image, a port conflict.
  3. my_history for that lab — checks whether something changed recently, such as a new startup script or a routing change.
  4. Explains the cause, and proposes a fix. For a broken startup script, it reads it with lab_startup_script, shows you the failing line, and fixes it once you agree.
  5. deploy_lab and wait_for_deploy — redeploys, once, and confirms.

What you get: the cause in plain words, and a lab that deploys. If the log says the lab's image does not exist on the platform, redeploying will not help — that one needs your administrator.

Do not let it retry blindly

A failed deploy fails the same way until the cause is fixed. A refusal because a deploy is already in progress means wait, not retry. See Deploy failed.

7. HTTPS is broken​

"My site says 'Not secure'. Fix it."

What the assistant does

  1. ssl_troubleshoot — scans your certificates and returns findings, each with a fix.
  2. Tells you which kind of problem it is:
    • The domain's DNS points somewhere else. Only you can fix this, at your domain registrar. The assistant tells you which record and what it currently points at.
    • Old names the platform is already cleaning up. Nothing to do; it says so rather than sending you after them.
    • The certificate expired or is failing to renew. It offers to request a replacement.
    • No findings. The certificates are fine — it checks that the lab is running and the domain is attached to it instead.
  3. request_ssl_reissue, if you agree — files the replacement request.

What you get: a clear answer about where the fault is. A re-issue request is reviewed by an administrator and applied on a schedule, so it is not instant; list_ssl_certificates shows its progress. After a DNS change, wait for the platform's next check before asking again. See HTTPS not secure.

8. Add a laptop to the VPN​

"Add my laptop to the VPN and give me the config file."

What the assistant does

  1. list_devices — checks how many devices you have against your limit.
  2. add_device — registers "laptop". If you give it your laptop's WireGuard public key, the platform never holds a private key for it; otherwise the platform generates the pair.
  3. device_config — returns the configuration file.

What you get: a WireGuard configuration to import into the WireGuard app. Once connected, you can reach your labs' private addresses. Works on a Free account.

The config file can contain a private key

Treat it like a password. Do not paste it anywhere else, and delete the device (delete_device) if the file leaks.

9. Build and share your own lab template​

"Make me a template called 'Node Starter' based on Ubuntu with Node 20 installed, and share it with my study group once it works."

Needs template authoring enabled for your account — see Who can author templates.

What the assistant does

  1. list_categories, then create_template — creates a private draft.
  2. write_template_file — writes the Dockerfile that installs Node 20.
  3. configure_template — CPU, memory, ports.
  4. template_status — checks the template is ready to build.
  5. build_template and wait_for_build — builds the image; on failure, template_build_log shows why and the assistant fixes the Dockerfile.
  6. configure_template — moves it from alpha to beta, which is what allows deploying and sharing.
  7. set_template_slug — confirms the lab id with you, because it is fixed after the first deploy.
  8. deploy_template and wait_for_deploy — the first deploy. It checks with lab_probe or run_command that Node is really there.
  9. share_template — shares it with the people or workgroup you name.

What you get: a working template your group can deploy. Sharing needs a paid plan or 7,500 Zeal. Any later edit returns the template to draft — it still deploys, but needs a rebuild before it can be shared again. See Templates.

10. Onboard people into an organization​

"Add these four people to acme-labs as members, make Priya an admin, and give them a PostgreSQL user they can share."

What the assistant does

  1. whoami — checks that you can act for acme-labs.
  2. org_add_members — adds the four people in one step and reports each result.
  3. org_set_member_role — makes Priya an organization admin.
  4. add_service_user for acme-labs — creates the database user as the organization, so it belongs to it and its members share it.
  5. org_overview — shows the organization's members, networks, domains, services and storage afterwards.

What you get: the team in place and a shared database user, owned by the organization rather than by you. If you belong to a department inside acme-labs, the assistant acts as that department instead. See Acting as an organization and Members and roles.

When someone leaves, ask "What would move if I transfer Ravi's things to me?" — the assistant runs org_transfer_preview, which changes nothing and lists exactly what would move and what blocks it (running labs must be stopped first). Only then, if you agree, org_transfer_execute. See Moving resources.

Next​