Instance Access

Open an interactive terminal on your own compute instance with fm shell. The instance's agent dials out to Frostmoln and the terminal rides that connection, so this path needs no public IP, no open port, nothing listening on the instance and no key of yours — and it opens no inbound route to reach.

It is not SSH: it does not use port 22, no key is involved, and there is nothing for you to open in a security group — which is why the command is fm shell rather than fm ssh (both fm ssh and fm session still work as aliases). This changes nothing about the instance itself: whatever it listens on, it still listens on, and SSH to your own instance is unchanged and fully supported; instance access is an additional way in, useful exactly when SSH is not: an instance with no public IP, a security group that shuts you out, a key you no longer have.

It is chosen when the instance is created

It cannot be added to an existing instance

An instance can be reached this way only if it was created with instance access enabled. The agent takes its identity from the instance at first boot, and there is no path to enrol an instance that is already running. To give an existing instance a shell, re-create it.

Enable it at create time, from the CLI or from Terraform. The portal's create form does not offer it yet.

fm compute instance create \
  --name web-1 \
  --image <image-id> \
  --flavor gp1.small \
  --instance-access

resource "frostmoln_instance" "web" {
  name            = "web-1"
  instance_access = true
  # ...
}

In Terraform, instance_access is create-time only. Changing whether the agent is installed forces replacement (false and unset both mean no agent, so moving between those two does not). The API does not return it and terraform import leaves it unset, so instance_access = true on an imported instance plans a replacement.

The image has to be able to run the agent, and the instance has to keep reaching Frostmoln outbound for as long as you want a shell. Platform images already do both. If you boot your own image, see Custom Images for what the installer needs and for the two ways enrolment fails quietly.

Instance access is x86_64 Linux only: the agent needs that architecture plus systemd and cloud-init, so Windows instances cannot use it. Reach those over the console instead.

Open a shell

fm shell 9b6b2d0e-1f4c-4a7e-9c3d-2b8f5e6a1d04

The argument is the instance id, not its name. Type the start of either and tab completion fills in the id.

Put a command after -- to run it instead of opening a shell:

fm shell 9b6b2d0e-... -- systemctl is-active nginx

That form is script-safe — output is not line-ending-mangled, and the command's own exit code becomes fm's exit code. One thing to know when redirecting: the command's stdout and stderr arrive merged on fm's stdout, so fm shell … -- cmd > out.txt captures both. Add --tty if you need a terminal allocated anyway.

Which user you get

You land as the image's default user — debian on Debian, ubuntu on Ubuntu, and so on. On the platform images that is the same user SSH gives you. Log in as someone else with --user:

fm shell 9b6b2d0e-... --user deploy

A custom image with no usable default user gives you a root shell

The login user is resolved from the image when the instance is created, and every way that resolution can fail lands you on root instead — silently. It fails when the image declares no default user, when its distribution is not one the platform recognises, and when the name it declares is not usable as a login account. That last one is the trap: a name containing capitals, such as MyUser, is accepted when you upload the image and shown as the login user, but the session still runs as root.

If you do not want a root shell, give the image a default user named in lowercase before you create instances from it, and check which user you actually land as the first time.

Sessions are time-limited

A session ends after 10 minutes without activity, or 1 hour in total, whichever comes first. Status 255 means the session died — a limit, a dropped connection, or fm itself being killed. If fm cannot open the session at all it exits 1 with a message on stderr. Any other status is your own command's.

What controls access

• Your own organization's instances. You can open a shell on instances in the tenants your organization owns. Anything else is not found — the same answer whether the instance does not exist or is not yours.
• Only where you enabled it. Instance access is per instance and set at create time. An instance created without it cannot be reached this way at all, by anyone.
• Time-bounded. No session stays open indefinitely.

There is no per-member restriction yet — and a tenant is not a fence

Any active member of your organization can open a shell on any instance with instance access enabled, whatever their role, and in any tenant your organization owns — not only the tenant they normally work in. So do not treat a separate tenant as an access boundary here: putting a sensitive workload in its own tenant does not keep your other members out of it. Any of that tenant's API keys can open a session too.

No setting narrows this to particular people, and no access policy fences it either.

Until one does, the create-time switch is the boundary: leave instance access off on the instances where it matters, and reach those over SSH, where you decide who holds a key.

For API keys specifically, sessions:pty is the scope that will bound this, and nothing else stands in for it — not compute:*, and not a wildcard, which a key may not hold. Grant it now to any key that runs fm shell, so your keys are already right. Do not rely on it as a boundary yet: it is not checked when a session is opened, so today a key without it still opens one. See API keys.

What enabling it puts on the instance

Worth knowing before you turn it on, because it is your machine:

• The agent runs as root, and deliberately without the sandboxing the platform applies to its own managed instances — it has to be able to start a shell as whichever user you ask for.
• Its identity credential is readable by any process on the instance, the same posture as an instance-role credential on other clouds.
• A snapshot or image of an enrolled instance carries that identity, and something restored from it can act as the original. Treat an image taken from an enrolled instance as sensitive, and prefer building images from instances that never had instance access enabled.
• Sessions create no login record, so who, last and utmp do not show them. Audit inside the instance if you need a trail.

When it doesn't work

What fm tells you	What to do
instance not found or instance access not enabled	The id is wrong, the instance is not in this tenant, or it was created without instance access. On a just-created instance, the agent may still be installing.
this instance can't do terminal sessions	The instance has an agent, but not one that serves terminals. fm also suggests updating the agent; there is no agent-update path yet, so re-creating the instance is the only route.
the instance's agent is offline	The instance is stopped, still booting, or has lost its outbound path to Frostmoln. Retry shortly.
the instance agent is up and at its session limit	Too many sessions are open on that instance at once. Close one — retrying alone will not help. If it persists when you have none open, contact support.
session ended by the platform	The idle or total limit ran out, or the connection dropped. Open a new session.

If a brand-new instance never accepts a session, the enrolment failed: on the instance, /var/log/frostmoln-managed-agent-install.log and /var/log/cloud-init-output.log name the reason. If it worked and then stopped, check the instance can still reach Frostmoln outbound. Custom Images covers both in full, including what a stripped-down image is usually missing.

Limits

• Create-time only. Instance access cannot be enabled, or disabled, on an existing instance.
• CLI and Terraform only. The portal cannot enable it and does not offer a terminal.
• x86_64 Linux only — the agent needs that architecture, systemd and cloud-init.
• Not on launch templates or scale groups — neither carries an instance-access setting, so instances they create never have a shell.
• 10 minutes idle, 1 hour total per session, and a limited number of concurrent sessions per instance.
• No per-member or per-key restriction yet (see above).

Related

• Compute / Instances · Custom Images
• API keys · fm CLI · fm shell reference