Skip to Content
Getting startedAs an owner

Getting started as an owner

Go from a fresh install to a working organization, with your team invited and your first agent connected. The owner is the first person to sign in to a new Marshal install.

An owner has all admin rights. An owner can also rename or delete the organization and change member roles. See Owners, teams and scope.

Claim the organization

You do this once, right after Marshal is installed. You need the setup token.

Your operator runs this. The person who installed Marshal reads the setup token from the cluster and sends it to you over a private channel. With the default release name marshal and namespace marshal, the command is:

kubectl get secret marshal-app-secrets -n marshal -o jsonpath='{.data.SETUP_TOKEN}' | base64 -d

The secret is named <release name>-app-secrets, and the key is SETUP_TOKEN. If your operator supplies their own app secret, the key lives in that secret.

  1. Open /setup on your Marshal address, for example https://marshal.example.com/setup. Until the install is claimed, every page of Marshal brings you here. Your operator can also send a link that ends in /setup#token= followed by the token, which fills the token in for you.
  2. Fill in the form “Set up your instance”:
    • Setup token: paste the token.
    • Email address: the email you will sign in with.
    • Name (optional): shown in audit events.
    • Password: at least 8 characters.
    • Organization name (optional): if you leave it blank, Marshal derives it from your email.
  3. Select Claim instance.

What you should see: you are signed in and land on Home. The top bar shows your organization name and the role owner.

Claim from a terminal

No browser on the machine you are working from? The “Set up your instance” form makes one request, and you can make it yourself. Read the token and the password without echoing them, so neither lands in your shell history. They reach jq through its environment, so neither shows in the process list either:

read -rs SETUP_TOKEN    # paste the setup token, then Enter
read -rs PASSWORD       # at least 8 characters
SETUP_TOKEN="$SETUP_TOKEN" PASSWORD="$PASSWORD" \
jq -n --arg email you@example.com --arg org_name "Example Inc" \
  '{token: env.SETUP_TOKEN, email: $email, password: env.PASSWORD, org_name: $org_name}' |
curl -sS -X POST https://marshal.example.com/api/auth/setup \
  -H 'Content-Type: application/json' --data @-

Use your own Marshal address. name is optional too: add it to the object to set the display name. A 201 response means you are the owner, and the body carries your signed-in session. 409 with already_initialized means someone claimed the install first. Then sign in from the CLI with marshal login --server https://marshal.example.com.

The setup token claims the install only once, while no account exists. If the page says “This instance is already set up”, the install is claimed. Select Go to sign in. If it says “Setup is not enabled”, the app secret has no SETUP_TOKEN key. Your operator adds it to turn on first-run setup.

If you lose the owner password

After the claim, the setup token keeps one job: a break-glass password reset. On /setup, select Reset the owner password instead, then enter the setup token, the owner email and a new password.

Choose how people sign in

You reach all settings from the organization chip at the top right. Select it, then select Organization settings.

  • Email and password. The login page shows “Email address”, “Password” and Sign in. It is on by default.
  • Google. Your team selects Continue with Google on the login and register pages, after you set it up below.

Set up Google sign-in (optional)

  1. Create an OAuth client in your Google Cloud project. Copy the client ID and client secret.
  2. In Marshal, go to Settings, then Authentication.
  3. In the Google card, select Configure.
  4. Turn on Enable Google sign-in.
  5. Enter Client ID and Client secret.
  6. In Allowed domains, type an email domain and press Enter. Leave it empty to allow any domain.
  7. Select Save changes.

What you should see: the card shows the badge “Enabled”, and the login page shows Continue with Google.

People join your organization with an invite link. Anyone without one sees “Registration is invite-only.” on the register page. Your operator can open registration for the whole install, so that anyone can sign up and get their own organization.

Set up email (optional)

With email, Marshal sends invitations and password-reset messages for you. Without it, you copy invite links and send them yourself.

  1. Go to Settings, then Email.
  2. In the Provider card, choose Resend or SMTP. Enter the key or the mail server details.
  3. Turn on Enable email, then select Save provider.
  4. In the Default sender card, enter a From address. Select Save sender.
  5. Select Send test email.

What you should see: the message “Test email sent. Check your inbox.” The badge on the Provider card shows “Configured”.

Set up space storage

With storage, a space keeps its workspace when it stops, so your team can stop, start and archive spaces freely.

  1. Go to Settings, then Space Storage.
  2. In Provider, choose Amazon S3, Google Cloud Storage, Azure Blob Storage, or Filesystem / NFS.
  3. Fill in the fields for that provider, such as Bucket name. For Amazon S3, also enter the Region the bucket lives in.
  4. Select Test connection. Wait for “Connection OK”.
  5. Select Save & enable.

See Spaces and storage.

Turn on webhooks and Slack (optional)

Deputies and runs are on from the start. Webhooks let GitHub, Slack and your own systems start deputy missions, and the Slack connection brings questions from runs into Slack.

  1. Go to Settings, then Platform.
  2. Turn on Webhooks, Slack and OAuth sign-in, or both.
  3. Select Save changes.

What you should see: the message “Saved”, and Webhooks and Slack open in the settings sidebar. See Platform features.

Connect your first agent

Agents and integrations come from the marketplace. An admin or owner installs them, then each person connects their own credential.

  1. Open Marketplace in the left rail.
  2. On the Browse tab, find an agent, such as Claude Code, and a source tool, such as GitHub.
  3. Select Install on each. Pick a version if asked.
  4. Open Connections in the left rail, select Connect on the card, and follow the dialog.

What you should see: the package appears on the Installed tab, and your credential appears under Connections with a green status dot. See Connect GitHub and Add a Claude credential.

Publish your first stack

A new organization starts with no stacks. A stack is the template your team starts spaces from: an agent, its tools and the rules around them. Publish one and every member can launch a space. The quickest start is a ready-made stack from the marketplace:

  1. Open Marketplace in the left rail, then the Stacks tab.
  2. On default-engineering (Claude Code, Go, Node.js, Python and GitHub), select Install stack. Marshal installs its packages and creates a draft stack.
  3. Open Stacks in the left rail, open the new draft, and select Publish v1 →.

What you should see: the toast “Stack applied” after the install, then the stack card shows version 1. Members now see it when they create a manifest.

To build your own instead, select New stack on the Stacks page and add packages. Full steps in Build and publish a stack. From a terminal, see Set up from a terminal.

Invite your team

Go to Settings, then Members, and select Invite member. Choose Member or Admin, then send the link. Each link works once and is valid for 7 days. Full steps are in Invite a teammate.

Only an owner can change a member’s role, including making someone an owner. See Change a member’s role.

Hand day-to-day work to admins

You can run the organization alone. Most owners give day-to-day work to one or two admins. An admin can:

  • Invite and remove members, and reset member passwords.
  • Create teams.
  • Install and update marketplace packages.
  • Manage org-owned credentials, stacks and network policies.
  • Change organization settings, such as storage and retention.
  • Read the audit log for the whole organization.

Only an owner can:

  • Rename the organization.
  • Change a member’s role.
  • Remove another owner.
  • Delete the organization (Settings, Danger Zone).

To hand over, invite the person as Admin and point them to Getting started as an admin.

Keep at least two owners. The last owner cannot be removed, demoted, or leave the organization.

Next: launch your own first space

Your organization is ready. Now see it work: open your first space and give an agent a task.

Choose your roleAs an admin