# Machines and files - Obss

Define tasks
Machines and files
Give a task its starting folders and its machine, uploaded or imported from GitHub, so every run of that task starts the same way.
Files are the folders an agent finds in its working directory when a run starts, and the machine is the environment the run executes in. Both attach to a
task
, not to a treatment or the launch, so every treatment runs the task the same way and any difference in results comes from the tools. Obss saves each task’s files and machine at launch, so later edits don’t change launched runs (
why the comparison is fair
).
On a machine or folder,
Runs
lists every run whose task used it, in every experiment, and
Experiments
and
Frictions
list those runs’ experiments and frictions.
Files
A file is a folder such as a repository, sample data, or fixtures. The agent can read everything in it, so keep secrets out of files. Put API keys and tokens in
machine variables
or
tool values
, which you enter in the dashboard.
Add files
Open
Manage → Files
, select
Add files or folders
, and choose where the folder comes from:
Upload
adds folders or files from your computer. Each upload becomes one folder.
From GitHub
saves a snapshot of a public
github.com
repository, branch, and folder at the resolved commit, with the same steps as
importing skills
. To get later changes, open the folder and select
Check for updates
. Finished runs keep the content they used.
Attach files to a task
Open the task’s
Files
tab, search the project’s folders, and attach the ones the task needs.
Mount paths
Each file appears at a path relative to the agent’s working directory. In the dashboard, the path is the file’s name, such as
customer-fixtures/
. Use that path in the task instructions (“Fix the app in
helpdesk-web/
”), never an absolute path such as
/home/user/helpdesk-web
, where the agent can’t find the files.
From the CLI or the plugin, you set each file’s
mountPath
:
Use a relative path, such as
helpdesk-web
or
data/customer-fixtures
.
Use
.
to put the file’s contents in the working directory itself.
Give each file its own path.
Don’t start the path with
/
,
~
, a dot (except the path
.
itself), or the folder
task
or
environment
.
In a longer path, don’t use empty,
.
, or
..
parts.
Obss rejects a path that breaks a rule, and the error says which rule failed and how to fix it.
Git history
The agent always starts in a Git repository, and Obss keeps the history you give it:
An uploaded folder that contains a
.git
folder keeps its commits, branches, and authors. A snapshot from GitHub holds the files at one commit, without history.
A repository that a machine setup command clones into
/app
keeps its history too.
If the working directory has no repository when the agent starts, Obss creates one with a single commit of the files that are there.
The agent can read every commit you upload. Remove commits that contain the answer to the task, or a secret, before you upload the folder.
Machines
Make the machine a realistic developer setup for the person you’re building for. Each run gets a fresh machine, so nothing carries over between runs.
Standard Dev Machine
The
Standard Dev Machine
is a clean Ubuntu machine that Obss provides. You can’t edit or delete it, and it’s the project default until you set another.
Runtime
Version
Ubuntu
24.04
Node.js
24, with npm
Python
3.12, with pip
Git
2.43
It also has
bash
,
curl
,
jq
,
rg
,
ps
,
lsof
,
ip
,
netstat
,
psql
,
redis-cli
,
sqlite3
,
make
,
cc
,
c++
,
zip
,
unzip
,
xz
, and
bzip2
.
To give agents an API key, a token, or more packages, create your own machine, because you can’t add them to this one.
Create a machine
Open
Manage → Machines (Environments)
and select
New machine
. A machine you create starts from the Standard Dev Machine and adds what you set in these sections:
Section
What it holds
Variables
Environment variables that setup commands and the agent get, such as an API key. Obss stores each value encrypted
Packages
Programs and dependencies that you expect the user to have, each with a package manager
Setup commands
Shell commands that prepare the machine at the start of every run, before the agent starts (
when they run
)
Services
Programs that run beside the agent, such as a database or a local copy of your product, with an image, ports, and a ready check
A service has its own environment variables, and machine variables don’t reach it. To use one of the service’s variables in its command, run the command with a shell and write
$$NAME
, for example
sh -c 'exec redis-server --requirepass $$REDIS_PASSWORD'
. A ready check can’t use a value.
View as YAML
edits the whole machine as YAML. For a working example with a service, start from the
Redis on a custom machine
template.
Set as default
makes a machine the project default for new tasks. Tasks that already exist don’t change.
Choose a task’s machine
Open the task’s
Machine
tab and choose a machine.
When setup commands run
At the start of every run, Obss prepares the machine in this order:
Build
installs the machine’s packages and custom installs, then each CLI’s and SDK’s. Variables don’t exist yet, so anything that needs one belongs in a setup command.
Setup
runs the machine’s setup commands, then each CLI’s post-install commands in the order of the treatment’s tools. They run as the agent’s user in an empty
/app
, with the run’s variables set, so
mycli auth login --token "${MYCLI_TOKEN}"
leaves the CLI signed in for the agent.
Files that setup leaves in
/app
are part of the starting workspace, not the agent’s work, and a process that setup starts in the background keeps running while the agent works.
If a setup command fails
If a command fails or setup reaches its time limit, the run stops before the agent starts. Obss doesn’t retry it, and it doesn’t use your run balance. The run page names the command that failed, for example
CLI “mycli” post-install command 2 failed
, and says what to fix. Fix the command, then launch the experiment again. For the messages and the fix for each, see
Troubleshooting
.
Add required values
Mark a variable
Required
when a run can’t work without it. Until it has a value, the machine shows
Needs values
on
Machines (Environments)
, and a notice on
Home
names the missing values.
Add values
opens the machine.
You enter values only in the dashboard, and the CLI and the plugin return a link to the page. An empty optional value never blocks a run.
When two places set the same variable
The agent gets one value for each variable name. When a CLI or SDK declares the same name as a machine variable, the CLI’s or SDK’s value wins in its treatments, even when the tool has no value saved. Other treatments get the machine’s value. An info icon beside the variable on the machine page names the CLI or SDK.
Any other two places that set one name to different values stop the launch:
Two MCP servers
An MCP server and the machine, or an MCP server and a CLI or SDK
A custom agent and any of these
Any of these and the agent’s model provider, for example a CLI variable
OPENAI_API_KEY
next to an OpenAI connection
The same value in two places is fine. Different values give the blocker
variable_name_clash
, which names both places and the tasks, treatments, or agents it stops, but never the values. Remove or rename the variable in one place.
Edge cases: scheduled launches, later changes, and personal connections
A model provider’s own credentials are checked only for organization connections. A personal connection is checked when the run starts.
A scheduled launch isn’t stopped by this blocker. It starts as before, and only the runs with the clash fail when they start.
If a value changes after the launch check, the run stops when it starts.
A required machine variable can stay empty only when every treatment in the launch has a CLI or SDK that sets that name.
From the CLI and the plugin, the
definition
view of
obss resources inspect machine
and
inspect_resource
lists these names in
variableOverrides
, and
obss experiments preflight
and
preflight_experiment
return the blocker.
Node.js and agents
Every agent except Cursor runs commands with the machine’s own
node
and
npm
, the same ones your packages and setup use. Cursor uses the Node.js that comes with it. If setup changes Node.js, install it into
/usr/local
, not with nvm, and agents use that version too.
If an agent can’t run on the machine’s Node.js, the run stops when Obss installs the agent, and Obss doesn’t retry it. The run page shows
The agent can’t run on this Machine’s Node.js
with the versions, for example “Codex 0.167.0 needs Node.js >=22. This Machine has Node.js 20.11.1.” Change Node.js in setup or choose another agent, then launch again.
In November 2026, Codex, OpenCode, Qwen Code, and Pi moved from Node.js 22 and npm 10 to the machine’s Node.js 24 and npm 11, so their results before and after can differ.
Delete a folder or a machine
You can’t delete a folder or a machine that a current task version uses, and the delete preview names the reason. Choose another folder or machine on those tasks first. The
Standard Dev Machine
can’t be deleted.
From the CLI and the plugin
Task
CLI
Plugin (MCP)
Create or change a machine, or attach files to a task
obss resources apply
author_resource
Upload a folder or ZIP as a file
obss uploads create --kind file
create_upload
,
complete_upload
Find a public GitHub source
obss github browse
browse_github_source
Check a GitHub folder for updates, or set the default machine
obss resources lifecycle
manage_resource
Get the link to add required values
obss setup links
get_setup_links
List the experiments, runs, and frictions that used a machine or folder
--machine-id
or
--file-id
on
obss experiments list
,
runs list
,
frictions list
machine_id
or
file_id
on
list_experiments
,
list_runs
,
list_frictions
Next steps
Tools
Add the skills, MCP servers, CLIs, and SDKs your treatments compare.
Treatments (Toolsets)
Group your tools into treatments and keep a baseline.
Launch an experiment
Run your tasks with agents and treatments.
Tasks and rubrics
Tools
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform