Mirasim Documentation
Team spaces
A hosted Linux or Mac space where your coding agents stay on: sessions keep running after you close your laptop, and your team works together.
What a team space is
A team space is an always-on environment Mirasim hosts for your coding agents. Its workspaces, sessions, terminals and files live there, so sessions keep running when you close your laptop, lose the network or switch devices, and every device sees the same thing.
- Basic
- Linux · 2 cores · 4 GB RAM · 30 GB disk (expandable).
- Lite
- Linux · 4 cores · 8 GB RAM · 50 GB disk (expandable).
- Standard
- Linux · 8 cores · 16 GB RAM · 100 GB disk (expandable).
- Pro
- macOS · Apple silicon · 10 cores · 16 GB RAM — for work that needs macOS or Xcode.
- People
- 5 collaborator seats per space for admins and collaborators (the owner takes none), plus up to 100 observers who take no seat. To add seats, write to support@mirasim.ai. Chapter 13 covers adding people.
- Models
- Platform models run on space credit or personal credit; shared API keys are billed by their provider — see “Models and credits” below.
Getting a team space
Team spaces come with Collaboration: Basic, Lite, Standard and Pro run in our cloud and come with credits, and the plan on your own computer is free (chapter 14 covers attaching it). Prices are on the Pricing page (mirasim.ai/pricing).
Your account has a team space allowance: how many of each spec you can create. Without one, “New collaboration space” under “Add a space” says “Your account has no cloud spaces available”; once all are in use it says “All available cloud spaces are in use”. For more members or more spaces, write to support@mirasim.ai.
Create one
- Open the space menu
Click the space name at the top of the sidebar. “All spaces” in the menu lists this computer, your team spaces, and any space or computer shared with you.
- All spaces › Add a space › New collaboration space
“Add a space” asks where it comes from. “New collaboration space” is the one we host for your team; it shows how many you have left. On this computer before it is a collab space, “Get a cloud space” under All spaces opens the same choice.
- Pick a spec
“Collaboration space” or “Collaboration space · Mac”. A spec your account does not include says “Not enabled”. Once it is assigned, the team space appears in your space list.
- Set up its environment
Once it is ready, this window opens its Space settings › Environment & sync: its spec and runtime components, Agents and sign-ins, and its workspaces. You can come back to it from the space's settings at any time.

Under “Bring over from this computer”, “Sync” copies a local workspace up: its files, its sessions and the agents' memory. It is a one-time copy; the two sides do not sync afterwards, so move code between them with git. Credentials, ~/.ssh and ~/.aws are not copied.
Opening it
Click the space name at the top of the sidebar, then click a team space under “Recent” or on the “All spaces” page. It opens in its own window, or that window comes forward if it is already open. The window you clicked from stays as it was. The top of the sidebar shows which space a window is on.

- Opened
- It has a window already; under “Manage spaces” its row also shows who is online and how many sessions are running there.
- Available
- Click to open it in a new window.
- Offline
- The team space cannot be reached right now.
If the connection drops, the window reconnects by itself and the space menu shows when it will retry; “Reconnect now” tries at once. The team space keeps running while you are disconnected.
Working in a team space
A team space window is the same workbench as on your own computer — sessions, panes, files, Git, terminals — only everything runs in the team space. A few things are specific to it:
- Coding agents such as Claude Code and Codex are already installed. Project toolchains are yours to install, from the team space's terminal.
- Running pages: when an agent or your terminal starts a dev server, its localhost port is listed under “Running pages” on the tool rail at the right of the window — click to open it in the preview. A localhost link in a conversation opens in the preview too.
- Remote desktop: “Remote desktop” on the same tool rail shows the team space's screen, for example for a browser sign-in inside the space.

Pushing code as yourself
Settings › Linked accounts › Code hosting connects GitHub and GitLab. After that, agents and terminals in team spaces clone, pull and push as you. Each person connects their own account, and every git operation runs as whoever started it.
Calling AWS as yourself
Once AWS is connected, agents and terminals in team spaces access AWS as you, so the AWS CLI, SDKs, kubectl and Terraform work directly. Each person connects one AWS account.
- Open the connect dialog
Go to Settings › Linked accounts › Other services and select “Connect AWS”.
- Enter the AWS account ID
It has 12 digits. The dialog links to the AWS console, where you can look it up;
aws sts get-caller-identityshows it too. - If you have no access yet, ask the account administrator
The dialog then lists the AWS account, your email and the External ID. Send these three and the setup guide link, mirasim.ai/docs/cloud-hosts#aws-admin, to the account administrator, who does not need a Mirasim account. If you manage the account yourself, select “Create the role in AWS (CloudFormation)” instead.
- Verify again
When the administrator is done, select “Verify again”.
- Who uses it
- The AWS account you connect is used only for work you start. Other members of the space connect their own to access AWS.
- Region
- us-east-1 by default. For another region, set
AWS_REGIONor pass--region. - Credentials
- Temporary, renewed before they expire, and never written into the space’s environment variables or files.
- Losing access
- If the administrator removes you, Settings shows “No access”. Once access is restored, select “Verify again”.
For the AWS account administrator
A member wants to access the AWS account you manage from Mirasim, as themselves. For that, you create one IAM role in the account. You do not need a Mirasim account; everything is done in AWS.
How it works: through its own AWS role arn:aws:iam::475554723467:role/mirasim-aws-connect, Mirasim asks to use the mirasim-access role in your account (AssumeRole). Each request states the Mirasim sign-in email of whoever started the work, which AWS calls the source identity (sts:SourceIdentity). AWS allows the request only when that email is on the role’s list.
- Role name
mirasim-access. Fixed; it cannot be changed.- Who can use it
- The authorized users, which is the
sts:SourceIdentitycondition in the trust policy. List members’ Mirasim sign-in emails in lowercase;*@acme.comcovers a whole domain. Mirasim only uses a sign-in email the member has verified. - What they can do
- The policies you attach to the role. A new role has no permissions. Mirasim adds no restrictions of its own: what the role allows is what members can do.
- External ID
- The value starting with
mrs_acct_that the member sends you. Each AWS account has one, the same for every member. It is not a secret. - Credential lifetime
- One hour each; Mirasim renews them before they expire.
Create the role with CloudFormation
- Open the create-stack page
Sign in to the AWS console, then open the prefilled create-stack page. The template and the stack name
mirasim-accessare already filled in. - Fill in the member’s values
External ID: the value the member sent. mirasim sign-in emails: the member’s email; separate several with commas.
- Grant permissions
Under Policies to attach, enter policy ARNs, for example
arn:aws:iam::aws:policy/ReadOnlyAccess; Permissions boundary is optional. Left empty, the role has no permissions, and you can update the stack later. - Create the stack
Tick the acknowledgement at the bottom of the page that CloudFormation may create IAM resources, then create the stack.
- Tell the member
When the stack is created, ask the member to select “Verify again”.
To read the template first, open the template. If the member manages the account, “Create the role in AWS (CloudFormation)” in their connect dialog opens the same page, with their External ID and email filled in as well.
Create the role with Terraform
Replace <External ID> and the emails with the values the member sent. After applying, ask the member to select “Verify again”.
resource "aws_iam_role" "mirasim" {
name = "mirasim-access"
max_session_duration = 3600
assume_role_policy = jsonencode({
Version = "2012-10-17"
# Keep two statements: sts:ExternalId exists only on AssumeRole,
# so one combined statement would refuse the other two actions.
Statement = [
{
Effect = "Allow"
Principal = { AWS = "arn:aws:iam::475554723467:role/mirasim-aws-connect" }
Action = "sts:AssumeRole"
Condition = {
StringEquals = { "sts:ExternalId" = "<External ID>" }
StringLike = {
"sts:SourceIdentity" = ["alice@acme.com", "bob@acme.com"]
}
}
},
{
Effect = "Allow"
Principal = { AWS = "arn:aws:iam::475554723467:role/mirasim-aws-connect" }
Action = ["sts:SetSourceIdentity", "sts:TagSession"]
},
]
})
}
# What members may do. Replace with the policies you want to grant.
resource "aws_iam_role_policy_attachment" "mirasim_read_only" {
role = aws_iam_role.mirasim.name
policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}Managing access
- Add a member
- Add the member’s email to the authorized users, then ask them to select “Verify again”. CloudFormation: update the stack and edit mirasim sign-in emails. Terraform: edit the
sts:SourceIdentitylist. The role is created once; do not create it again for a new member. - Change permissions
- CloudFormation: update the stack and edit Policies to attach. Terraform: add or remove
aws_iam_role_policy_attachmentresources. - Remove a member
- Remove the email from the authorized users. Mirasim can no longer get credentials for that person; credentials already issued stop working within an hour.
- Cut access at once
- Remove the email first, then revoke the role’s active sessions in the IAM console (Revoke active sessions). Keep that order, or Mirasim gets fresh credentials. Revoking ends every member’s current session.
- A member changes their sign-in email
- Add the new email to the authorized users. Until then Mirasim gets no credentials for that person.
Audit and troubleshooting
- Who made a call
- In CloudTrail, every call carries the member’s email as
sourceIdentity, and the session tagmirasim:spacenames the space it came from. - Denied AssumeRole calls
- Expected when the session name starts with
mirasim-check-. Each time a member connects or verifies again, Mirasim sends three requests that must be refused (one without the External ID, one with an email not on the list, one that names no one) to confirm the trust policy turns them away. - The member still has no access
- Check three things: the role is named
mirasim-access; the External ID matches the one the member sent; the member’s Mirasim sign-in email is on the list, in lowercase. - The member is told the role needs an update
- The trust policy lets through a request it should refuse, or does not allow
sts:SetSourceIdentityandsts:TagSession. Usual causes: the list is a bare*, or the two statements were merged into one. Correct it against the Terraform above and keep the existing list. - Accounts not supported
- AWS China and AWS GovCloud accounts are not supported for now.
Models and credits
The team can use two kinds of models in the same space:
- Platform models
- Run on Mirasim credits. The credits that come with your plan go straight into the space credit and are shared by the whole team; anyone can add more from their personal credit.
- Shared API keys
- The owner or an admin connects any provider or relay under Settings › Model config. With “Share with members” ticked, everyone can pick it, billed to that key.
Setting up agents, keys and credits for the team is covered in chapter 13.
Where your data is
- Workspaces, sessions and the team's chat are stored in the team space.
- When a team space is reclaimed, everything in it is erased. Push code you want to keep to a remote repository.
Something wrong or missing on this page? Tell us