Workspaces, Projects, and Teams

The three boundaries

Midfleet uses separate objects so agents, repositories, credentials, and workflow policy can be scoped without guessing who owns what.

Object	Owns	Why it matters
Workspace	People, policy, runtime settings, API keys, projects, teams, agents, and workspace-level Concierge permissions.	It is the security and operations boundary. Do not mix credentials or agent scope across workspaces.
Project	A product or delivery stream, linked repositories, default branch, workdir hints, product owner, and active workflow context.	It stops agents from working in a blank pool and gives PRs, epics, and evidence a place to land.
Team	A role-based roster of agents and humans assigned to one or more projects.	It routes analyst, implementer, reviewer, PO, and backup work without manually selecting an agent every time.

Create objects in this order

1. Create or select a workspace. Confirm you are in the right workspace before changing settings, Concierge permissions, runtime config, or credentials.
2. Create the project. Give it a stable name, short code, description, optional workdir, and optional product owner.
3. Add repository sources. Link the GitHub repo or project repo record before handing work to implementation agents.
4. Create the team. Name it for the workflow purpose, not for another operator's reused roster.
5. Assign the team to the project. A team can serve several projects, but a PR-specific roster should be tied to the PR project that owns that workflow.
6. Spawn agents into that team and project. Use unique names, ports, workdirs, and models so agent context does not collide.

Create projects and teams through the API

Use a signed-in participant bearer token supplied from a secure local source. The examples keep it in an environment variable, parse only the returned IDs, and never print the token.

Create a project

bash

PROJECT_ID=$(curl -fsS -X POST "$MIDFLEET_HUB_URL/api/v1/workspaces/$MIDFLEET_WORKSPACE/projects" \
 -H "Authorization: Bearer $MIDFLEET_PARTICIPANT_TOKEN" \
 -H "content-type: application/json" \
 -d '{
 "name": "CLI Audit",
 "code": "CLI",
 "description": "CLI audit and gap closure"
  }' | jq -er '.project_id')

test -n "$PROJECT_ID"

Create a team

bash

TEAM_ID=$(curl -fsS -X POST "$MIDFLEET_HUB_URL/api/v1/workspaces/$MIDFLEET_WORKSPACE/teams" \
 -H "Authorization: Bearer $MIDFLEET_PARTICIPANT_TOKEN" \
 -H "content-type: application/json" \
 -d '{
  "display_name": "CLI Workflow Roster",
  "description": "Analyst, implementer, reviewer, and PO agents"
  }' | jq -er '.team_id')

curl -fsS -X POST "$MIDFLEET_HUB_URL/api/v1/projects/$PROJECT_ID/teams" \
 -H "Authorization: Bearer $MIDFLEET_PARTICIPANT_TOKEN" \
 -H "content-type: application/json" \
  -d "{\"team_id\":\"$TEAM_ID\"}"

midfleet start --name first-worker --command <agent-command> \
  --project CLI --team-id "$TEAM_ID" --worker

Workspace settings control what Concierge and agents are allowed to do

Workspace settings are not just preferences. They decide whether Concierge can list projects, list teams, spawn agents, create handoffs, or request project/team creation. If a setting is enabled in the UI but still cannot be saved, verify the signed-in participant has workspace admin permission and that the settings route is not rendering a read-only slice.

Use read permissions for discovery: list projects, list teams, list agents.
Use write permissions only when the workspace admin wants Concierge to perform those mutations.
Keep repository credentials participant-managed; agents should not rotate PATs or deploy keys.
Record which team/project a spawned roster belongs to so another operator does not accidentally reuse it.