Workspace and files

When you ask an assistant to write code, run tests or start a server, it works inside one of your labs, the way you would over SSH or in the web editor. By the end of this page you will know how it chooses the lab and folder, how it reads and changes files, the difference between a one-off command and a background process, and which of its work survives a redeploy.

Everything on this page needs a Pro account, and the lab must be running — a stopped or paused lab has nothing to work in.

Open a workspace

A chat client does not remember "where it is" between messages the way a terminal does. So the assistant pins a lab and a folder once, near the start of the conversation, and every later file, command and process request uses them.

What you can ask

• "Open my Essentials lab."
• "Open the api project in my Essentials lab."
• "What projects do I have in that lab?"
• "Work in my acme-labs team lab instead."

Tool	What it does
list_projects	Finds folders in a lab that are git projects, so you can pick one
open_workspace	Pins a lab, a folder (defaults to your home directory) and optionally an organization. Checks up front that you are allowed to work in that lab
workspace_info	Shows the current pin and re-reads the project's git state
close_workspace	Clears the pin
lab_workspace	Shows what is in the folder and what is running — a good first look

When the pinned folder is a git project, opening it also reports the branch, how many files are changed, whether you are ahead of or behind the remote, and the last commit. There are no special git tools: the assistant runs git commands like any other command.

How the pin behaves

• It lasts 24 hours, renewed every time it is used.
• Naming a different lab in one request ("check the logs in my Kali lab") acts on that lab for that request only. The pin stays where it was.
• It is a convenience, not a permission. Every request is still checked against what you are allowed to do.

Opening the workspace is also a safety net

While a workspace is open, the assistant cannot overwrite a file it has not read since that file last changed — so it will not clobber an edit you made in the web editor a minute ago. Creating new files is never blocked.

Reading, writing and editing files

What you can ask

• "Show me server.js."
• "Change the port in config.yml from 3000 to 8080."
• "Create a basic Express app with routes for /notes."
• "Find every file that mentions DATABASE_URL."
• "Rename utils.js to helpers.js."

Tool	What it does
read_lab_file	Reads a file, a page at a time for long ones
edit_lab_file	Replaces one exact piece of text. Refuses if the text appears more than once, instead of guessing
write_lab_file	Writes a whole file, creating folders as needed. Up to 2 MB
write_lab_files	Writes many files in one go — how the assistant scaffolds a project
list_lab_files	Lists a folder, with sizes and permissions
lab_file_tree	Shows a folder's whole shape at once
glob_lab_files	Finds files by name pattern, newest first
grep_lab_files	Searches inside files and returns file and line
move_lab_file	Moves or renames; will not overwrite unless you ask
create_lab_directory	Makes a folder; an existing one is fine
delete_lab_path	Deletes a file or folder
download_lab_file	Pulls a binary file out of the lab — a build output, an image, an archive. Up to 16 MB

Good to know

• Writes are all-or-nothing. A file is written in full and then swapped into place, so nothing ever reads half a file, and a failed write leaves the original untouched.
• Files are written as you, not as root, unless the assistant has a reason to write a system file. Files owned by root in your project would later be uneditable in the web editor and over SSH.
• Big downloads belong inside the lab. For anything over a couple of megabytes, the assistant should fetch it in the lab with git clone or curl rather than pushing it through the conversation.

Deleting is permanent

A lab has no undo and no trash for files. delete_lab_path cannot be reversed. A good assistant asks before deleting anything you did not ask it to delete — and you can tell it to always ask. See History and safety.

Commands versus background processes

There are two ways the assistant runs something, and picking the wrong one is the most common reason a server "starts and then disappears".

	run_command	start_lab_process
Use it for	Things that finish: installs, tests, builds, git	Things that keep running: dev servers, workers, watchers
Returns	When the command finishes, with its output and exit code	Straight away, with the process name and whether it is up
Time limit	60 seconds by default, up to 15 minutes	None
Output	Returned directly, up to 256 KB	Kept, and read with lab_process_logs
When the call ends	Anything it started is stopped	The process keeps running

What you can ask

• "Run the tests." — run_command
• "Install nginx." — run_command, as root inside the lab
• "Start the dev server and keep it running." — start_lab_process
• "Build the release and tell me when it's done." — start_lab_process, then wait_for_process
• "Is the API answering?" — lab_probe

Tool	What it does
run_command	Runs one command as you, or as root inside the lab (never on the host, and never in anyone else's lab)
start_lab_process	Starts a named background process in a folder, with optional environment variables
list_lab_processes	Lists what it started, and which ports are listening
lab_process_logs	Reads a process's output
stop_lab_process	Stops a process
wait_for_process	Waits for a background job to finish and returns its real exit code
list_tasks	Everything still in progress — deploys and processes
lab_probe	Sends one web request from inside the lab to a port, and reports the status and the start of the response

Good to know

• A started process is not proof it is running. A typo or a port already in use makes it exit at once. The assistant checks whether it is still up and reads its output if not; lab_probe confirms it answers.
• Nothing restarts a crashed process, and a redeploy stops them all. To have something start on every deploy, ask the assistant to put it in the lab's startup script, then redeploy.
• Running is not published. A server on port 3000 is reachable from inside the lab only. To open it in a browser, ask the assistant to route the port — see example 4.
• Labs have no systemd. systemctl fails inside a lab. Services are managed with sudo service <name> start|stop|restart.
• sudo asks for the lab password. A command that needs sudo works when run as root through the assistant; if it runs as you, sudo will prompt for the lab's password.

What persists

A lab is rebuilt from its image every time it deploys. Where the assistant puts things decides whether they survive.

Where	Survives a redeploy?	Shared with your other labs?
Your home directory	Yes	Yes — every lab mounts the same home
Programs installed with apt install	No	No
Changes under system folders such as /etc	No	No
Background processes	No — they stop	—

What this means when you work with an assistant:

• Keep projects in your home directory. That is where the assistant opens workspaces by default.
• A project is visible in every lab. Open the same folder from a different lab to build it with a different toolchain — but do not let two labs write the same file at once.
• Storage is per account. Filling your home in one lab fills it for all of them. storage_usage shows where you stand. See Storage.
• Put setup in the startup script. Anything that must be installed or started every time belongs there, not in a one-off command. Write it before the first deploy if you can.

Stop rebuilds; pause keeps

Asking the assistant to stop a lab and start it again is a full rebuild — only the home directory comes back. Pause freezes the lab with its running processes and memory intact. See Stop, pause and delete.

Steer it with an Agent Prompt

You can give the assistant standing instructions for a lab: where the code lives, how to run the tests, what not to touch. Open the lab → Preferences → Agent Prompt, write them, and click Save Agent Prompt. If you leave it empty, the assistant gets the template's own instructions instead. See Lab settings.

Next

• Worked examples — a dev server, a database and a site, end to end
• History and safety — what the assistant did, and what it cannot undo
• How labs work — the lab model behind all of this