How to Use Agent.Space: Start Your First Workspace Project

The best way to learn how to use Agent.Space is to start with one bounded, reversible project—not a complete migration.

Choose a task with an observable result, such as updating one page, reviewing one small code change, improving a defined document, or diagnosing a reproducible error. Create a Workspace, add only the files the task needs, select a supported Agent harness and compatible model, then judge the result against written acceptance criteria.

This tutorial takes that first project from setup to review and handoff.

Before you start, choose a small task you can verify

A useful first task should have four properties:

• Bounded: it touches a known part of the project.
• Reversible: you can restore the original files or discard the Workspace copy.
• Observable: a file, Preview, test, or other artifact shows what changed.
• Decidable: you can write down what “done” means before the Agent starts.

Good examples include:

• rewrite the copy in one landing-page section without changing layout;
• add one validation state to an existing form;
• review a small patch for a named risk;
• turn a supplied outline into one structured document; or
• reproduce one error and record the likely cause without implementing a fix.

Avoid “build my entire product,” “improve everything,” or “migrate the whole repository” as a first request. Those instructions hide decisions, make review difficult, and provide no clean rollback boundary.

1. Create a Workspace for the outcome

Open Agent.Space and create a new Workspace. Give it a name that describes the project or outcome rather than the Agent you expect to use. The Workspace is the shared container for members, Sessions, saved files, and working context; the Agent is one participant inside it.

For example, Launch page copy review is more durable than Codex test. If you later use Claude Code or OpenCode for another Session, the Workspace name still describes the project.

The deeper product model is covered in how Agent.Space works: a Session carries one continuing Agent task, while the Workspace keeps the saved project available across Sessions.

2. Add a brief and only the necessary files

Before starting a Session, prepare a short brief. Include:

• the desired outcome;
• the files or source material that define the task;
• what may be changed;
• what must not be changed;
• how the result will be verified; and
• any decision that requires human approval.

Add the relevant files to the Workspace. Do not upload an entire archive simply because it is available. Extra material can introduce conflicting instructions, private data, or irrelevant context.

Keep credentials out of prompts and ordinary project files. If the task needs access to another service, use an approved secret-management or environment path and grant only the permission required for that test.

3. Choose an Agent harness and a compatible model

Agent.Space lets you choose the Agent harness and model separately. The harness organizes tools, permissions, context, and the execution loop. The model supplies the underlying capability. They are related, but they are not the same choice.

Use the live Agent and model selectors as the source of truth for supported combinations. Not every model works with every harness, and availability can change.

For a first project, choose based on the job you can evaluate rather than trying to find a universal “best Agent.” A build task, a focused review, and a document transformation may benefit from different workflows.

If Codex is the harness you want to evaluate first, follow the Codex on Agent.Space walkthrough for the exact Workspace-to-review loop.

Also confirm how the selected model use will be funded. Agent.Space Share and Flex serve different access patterns; selecting a model determines the relevant source, and one balance does not silently replace the other.

4. Write a task with an acceptance contract

A strong first prompt describes the result and the checks, not every keystroke. Use a structure like this:

GoalUpdate [specific artifact] so that [observable outcome].
In scope- [file, section, or behavior that may change]- [source material to follow]
Out of scope- [area that must remain unchanged]- [external action that requires approval]
Acceptance checks- [test, Preview state, or content requirement]- [second success condition]
Before finishingSummarize changed files, checks run, unverified assumptions, and the next recommended step.

This gives the Agent enough room to work while preserving review boundaries. If the task requires a subjective choice—such as selecting a design direction—ask for options and stop for a human decision before implementation.

5. Start the Session and watch the evidence

Choose the Agent, confirm a compatible model, attach the necessary files, and send the bounded task. Agent.Space creates the Session and starts the first Turn.

During execution:

• use the Queue for follow-up requests rather than repeatedly submitting the same instruction;
• respond to permission requests based on the exact action and target;
• keep external or destructive actions behind an explicit approval point;
• inspect intermediate files when a decision depends on them; and
• avoid changing the task’s objective halfway through without rewriting the acceptance criteria.

An active Agent response is not the final project truth. The saved files, visible result, and validation output are the evidence you will review.

6. Review files, Preview, and validation

When the Turn finishes, compare the result with the brief.

1. Read the Agent's summary and note any stated limitation.
2. Inspect the actual saved files and look for unrelated changes.
3. Open supported output in the Inspector or browser Preview.
4. Run the checks that match the project: tests, build, lint, type checks, content QA, or another relevant gate.
5. Record checks that were not run and assumptions that remain unverified.
6. Decide whether to accept, request one bounded revision, or restore the prior state.

Preview, publishing, and file delivery are separate decisions. The guide to Preview, publish, and export explains when to keep a temporary review view, create a stable web Release, or download an ordinary file.

Do not accept work only because the rendered output looks polished. A correct review also checks scope, files, behavior, permissions, and the evidence behind factual claims.

7. Save a handoff state before the next Session

Even a solo project benefits from a short handoff record. Write down:

• the requested outcome;
• the files that changed;
• the checks that passed or failed;
• the current Preview or delivered artifact;
• remaining decisions and risks; and
• one next action with a completion condition.

If another Agent should review or continue the project, start a new Session in the same Workspace. The new Agent can inspect the current saved files and the explicit handoff material. It does not silently inherit the previous Session's private reasoning, so put essential decisions in an inspectable file or message.

Common first-project mistakes

Starting with a complete migration

You learn less from a large task because failures can come from scope, setup, permissions, model choice, missing files, or unclear requirements. A small task isolates the workflow.

Uploading context without a hierarchy

Ten documents do not help if the Agent cannot tell which one is authoritative. Name the primary brief and explain how supporting files should be used.

Confusing an Agent with a model

Changing the model does not automatically change the harness workflow. Check both selections and confirm their compatibility.

Treating the Agent summary as validation

The Agent can report what it attempted. You still need to inspect the actual artifact and relevant checks.

Leaving no restart instructions

A Workspace can preserve saved files while a Runtime process stops. Record the command and evidence needed to resume instead of assuming every process will continue indefinitely.

Expanding scope during review

If review reveals a new project objective, make it the next bounded task. Do not hide a second project inside an ambiguous follow-up.

Finish one complete loop, then scale up

Your first Agent.Space project is successful when you can trace a complete loop: a bounded brief entered the Workspace, one compatible Agent-and-model combination performed the task, the saved output passed the relevant review, and the next step is clear.

Only then should you add a larger codebase, more Sessions, another Agent, or teammates. That sequence teaches you which part of the workflow is creating value without making the first experiment difficult to diagnose.

Open Agent.Space and create a Workspace for one reversible task. Name the expected outcome, add the minimum source material, define the acceptance checks, and finish the full review loop before expanding the project.