# Your FlintVM workspace

FlintVM gives you a Linux environment for development, desktop applications and AI work. Open **Workspace** and sign in with your account. If you received an invitation, follow the invitation flow on the sign-in page. See [sign-in and CLI login](/docs/sso.md).

## Create an environment

1. Choose **New environment** and give it a name.
2. Choose a template or custom configuration, then select an available distribution and release. Arch Linux is rolling and has no release choice.
3. Select a resource plan from the options available to your account.
4. Choose desktop and AI controls, search for packages, and select encrypted disk storage if available.
5. Create the environment. Start its desktop or run a command when you are ready to use it.

Creation saves your choices. The first start can take longer while software is prepared. You do not need to choose or configure a server. If no capacity or suitable plan is available, contact your administrator.

## Use the desktop

Open your environment and choose **Start desktop**. Wait until it is running, then connect the Computer viewer. Choose **Take control** to use the mouse and keyboard. **Match display** adjusts the desktop resolution to the viewer, including in fullscreen.

For native SSH, VNC or Xpra clients, open **Details → Remote connections** and follow the [connection guide](/docs/remote-access.md). Available connection methods depend on your account and environment.

## Connect an AI agent

Open **Agent connections** to create a scoped API key or configure your harness. The [MCP guide](/docs/mcp.md) explains setup; the [agent quickstart](/docs/agent-guide.md) covers creating environments, running commands and transferring files. Agents act within your workspace permissions.

## Change environment variables

Open **Configuration → Environment variables**, edit the `KEY=value` entries and choose **Save variables**. You can save while the desktop runs. New agent commands and future starts use the new values; existing applications keep their current environment.

Agents can read saved values. Use these fields for configuration, not secret storage. Other configuration changes may require stopping the environment or creating a new one.

## Save installed software and files

Install your software and save your work, then stop the environment. In **Saved images**, choose a name and select **Save image**. Wait for completion before creating another environment from that image.

A clone gets an independent writable disk. Saved images capture disk contents, not running processes or open network connections. Treat image deletion and environment deletion as permanent actions; check the selected item before confirming.

## Network access and privacy

Outbound browsing does not need a port mapping. A port mapping is an optional inbound connection to a service inside your VM, such as a development web server. Availability depends on your account’s policy.

Your environments and agent credentials belong to your account. Team membership does not automatically share VMs. Encrypted disks protect stored data while locked; they do not protect running memory from the host administrator. Memory protection from the host is currently unavailable.

## Idle shutdown and interruptions

The default idle shutdown is ten minutes; active AI commands prevent idle shutdown. Account settings can impose other time limits. Save your work regularly.

If the connection drops, check the environment and task status before repeating work. During service maintenance, wait until the environment is ready and reconnect using its existing name. If an infrastructure or storage error persists, send the error to your administrator.