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
# (shows the enrollment and the policy bundle status)
ssg fleet status
ssg fleet status --json

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 Fleet URL and the profile token
ssg fleet enroll <fleet-url> 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. The ssg CLI has no command that lists the agents of an org; ssg fleet status shows the state of the current machine only.

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

For a lost or compromised device, a Fleet admin revokes the agent in the Fleet Dashboard under Agents. The CLI has no command for this. After a forced revoke the machine cannot re-enroll without admin action.

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