Skip to main content

Adding a Device to SigmaShake Fleet

There are two ways to enroll a machine into your fleet org.

PathWho triggers itWhen to use
Self-enroll ("Connect this machine")The developer themselves, via WorkspaceThe default — no admin token needed; the developer's existing SSO session is the credential
Admin-issued enrollment profileFleet admin generates a token; developer uses itHeadless / CI environments; onboarding scripts; situations where the developer does not have a Workspace session

This is the "Connect this machine" flow. A developer who is already a member of your Fleet org can enroll their own machine without any admin intervention.

Prerequisites​

  • The developer has a SigmaShake account and is a member of your Fleet org.
  • ssg CLI is installed on the machine — see Getting Started for the platform-specific install command.
  • The developer is signed into ssg: ssg auth login

Steps​

  1. The developer opens workspace.sigmashake.com and signs in.
  2. They click Connect this machine in the Fleet section of their dashboard.
  3. The Workspace browser tab calls the Fleet API to mint a 5-minute single-use enrollment grant (tied to the developer's session and org).
  4. The Workspace UI hands the grant to the local ssg daemon, which calls POST /api/v1/agents/self-enroll automatically.
  5. On success, ssg stores the resulting agent JWT in ~/.sigmashake/fleet.toml. The machine appears in the Fleet dashboard under Agents within seconds.
Grant security properties

The enrollment grant is single-use — a leaked bearer cannot enroll a second machine. It also expires after 5 minutes even if unused. If the enrollment fails for any reason (quota exceeded, revoked machine, expired grant), the developer must click Connect this machine again to get a fresh grant.

Checking enrollment status​

# Verify the machine is enrolled and healthy
ssg fleet status

# Show the current agent ID and org
ssg fleet whoami

Path 2: Admin-issued enrollment profile token​

Use this path for headless servers, CI runners, or bulk onboarding scripts where the developer does not have an active Workspace browser session.

Steps​

  1. Fleet admin: In the Fleet Dashboard, go to Settings → Enrollment Profiles.
  2. Click Create Enrollment Profile and configure:
    • Name — a label for this profile (e.g., "CI runners" or "Dev team Q3")
    • Max uses — how many machines can enroll with this token (or leave blank for unlimited)
    • Expiry — when the token stops accepting new enrollments
  3. Copy the generated profile token (ssg_ep_…).
  4. Send the token to the developer or script.

On the target machine:

# Enroll using the profile token
ssg fleet enroll --token ssg_ep_your_profile_token_here

# Confirm enrollment
ssg fleet status
Profile token scope

A profile token is valid for new enrollments only — it cannot re-enroll a previously revoked machine. If a machine was revoked by an admin, contact the Fleet admin to issue a new enrollment or explicitly re-activate the agent in the dashboard.

Checking enrolled machines​

Fleet admins can view all enrolled machines in the Fleet Dashboard under Agents, or via the CLI:

# List all active agents in your org
ssg fleet agents list

# Filter by status
ssg fleet agents list --status active
ssg fleet agents list --status stale

The Fleet Dashboard shows each agent's last heartbeat, lifecycle state, ssg version, and policy compliance status.

Removing a machine​

# Graceful unenroll from the current machine (the machine can re-enroll later)
ssg fleet unenroll

# Forced revoke from the admin dashboard or CLI (the machine cannot re-enroll
# without admin action — use for lost or compromised devices)
ssg fleet agents revoke --agent-id <AGENT_ID>

After a graceful unenroll the agent record is kept with status=revoked so the same machine can re-enroll later. A forced admin revoke also keeps the record but marks unenroll_reason=forced — the machine is blocked from re-enrollment until an admin explicitly re-activates it.

Troubleshooting​

SymptomLikely causeFix
"Enrollment bearer expired or already used"Grant expired (> 5 min) or was already consumedClick Connect this machine again in Workspace
"Organization agent quota reached"Your org has hit its seat limitContact sales or remove unused machines
"This machine was previously revoked"The machine was force-revoked by an adminAsk a Fleet admin to re-activate the agent record
ssg fleet status shows not enrolled after enrollmentThe agent JWT was not savedRe-run the enrollment; check ~/.sigmashake/fleet.toml permissions