Skip to Content
How-to guidesYour first task

Your first task, end to end

Go from zero to a pull request written by your agent. You connect Claude and GitHub, build a manifest, start a space, and give the agent a real issue from your own repository. You watch it work, approve what it needs, review its changes, and ship them. Then you hand the next task to a run that works on its own.

Before you start

  • You are a member of a Marshal organization. Any role works.
  • An administrator has installed the GitHub package and published a stack that includes Claude Code and GitHub. See Build and publish a stack.
  • You have a Claude API key or a Claude.ai login, and a GitHub repository with a small issue you want fixed. A failing test, a typo in the docs, or a missing input check are all good first tasks.

1. Connect Claude

  1. In the left rail, open Connections.
  2. On the Claude Code card, click Connect.
  3. Choose the API Key tab or the Setup Token tab, paste the value, and click Save.

Full steps: Add a Claude credential.

What you should see: Claude Code under Your connections with a status dot.

2. Connect GitHub

  1. On the same page, on the GitHub card, click Connect.
  2. Pick Sign in with GitHub, or paste a Personal access token, and finish the dialog.

Full steps: Connect GitHub.

What you should see: a GitHub row under Your connections with a green status dot. Your agent can now clone, push, and use gh. It never sees the token. Marshal adds it to each request on the way out.

3. Create a manifest

A manifest is your saved recipe: the stack your administrator published, plus your own choices.

  1. In the left rail, open Manifests, then click New manifest.
  2. Enter a Name, for example my-first-agent.
  3. Under Stack, choose the stack. Under Version, choose a version.
  4. Click Create.

Full steps: Create a manifest.

What you should see: the manifest in the table, with “ready” in the Status column and a Launch button on its row. If the status asks you to add a credential, go back to Connections and connect it.

4. Start a space

  1. On the manifest’s row, click Launch. The manifest is already picked.
  2. Click Create Space.
  3. Wait on the Starting space page while Marshal sets up the environment.

Full steps: Create a space from a manifest.

What you should see: the Ready to connect card: “Your space is up and the agent is waiting.” Your agent now has its own isolated machine, with your credentials wired in and a network policy around it.

5. Give the agent its first task

  1. On the space page, click Open Terminal. Claude Code is waiting for you.

  2. Type the task the way you would brief a teammate. Name the repository, the issue, and what “done” means. For example:

    Clone github.com/acme/billing. Fix issue #42: the invoice total
ignores the discount when the cart has more than one item. Add a
test that covers it, run the test suite, and commit on a new branch
named fix/discount-total.

  3. Watch it work. The agent clones the repository, reads the code, edits files, and runs your tests, in the terminal in front of you.

Prefer your own terminal? Run marshal spaces connect <space-name> from your machine. See Install the CLI and sign in.

What you should see: the agent’s plan, then its edits and test output, as it goes. Click the panel icon in the toolbar (Toggle inspector panel) to open the right panel. Its Activity tab lists the space’s events as they happen.

6. Approve a blocked domain

Your space blocks every outbound connection that no rule allows. Say the agent needs to download a package from registry.npmjs.org and the stack does not allow it yet. Marshal blocks the call and asks you.

  1. In the right panel, open the Blocked tab. It appears when something was blocked, with a red count.
  2. On the card for the domain, click Approve. To keep the rule for every future space from this manifest, open the arrow next to Approve and pick Approve & remember for next run.

Full steps: Approve a blocked domain.

What you should see: the card changes to “Approved”. The agent’s next try works. The space does not restart, and the approval is in the audit log with your name.

7. Review the changes

  1. In the right panel, open the Changes tab.
  2. Each repository shows its branch, how far it is ahead of upstream, and the changed files. Files are grouped under Uncommitted and the commits on this branch.
  3. Click a file to read its diff. Click Refresh to see the latest.

Not happy with something? Tell the agent in the terminal: “Rename the helper to applyDiscount and keep the old tests passing.” Then check Changes again.

What you should see: the files you expected, with + and − line counts, and the new test.

8. Open the pull request

The agent owns git in its space, so you ask it to ship:

Push the branch and open a pull request against main. Link issue #42
in the description and summarize the change and the test you added.

The agent runs git push and gh pr create with your GitHub connection.

What you should see: the pull request URL in the terminal. Open it on GitHub. It is your branch, your commits, and your review flow, written by your agent.

9. Hand the next task off as a run

You do not have to watch every task. A run gives the agent a task and lets it work on its own space, from start to finish, while you do something else. From your terminal:

marshal run --manifest my-first-agent \
  --task "Clone github.com/acme/billing and fix issue #43. Open a pull request when the tests pass." \
  --follow

Runs are available when your administrator enables runs and deputies. In the web app, you start runs from a deputy. See Start a run in the web and follow it.

What you should see: run <run-id> started (space <space-id>), then the agent’s output as it works, and a final line with the run’s status. The run also shows on the Runs page, where you can read its Activity and Changes and answer any question it asks.

Next

Make it repeatable: create a deputy and a mission, so the next fix is one click, a schedule, or a GitHub event away.

All how-to guidesInstall the CLI