Create and Use a Remote Workspace
Step-by-step developer journey for Remote Workspaces — register OAuth apps and MCP servers, store credentials, create a workspace from a template, and open it from the browser or over SSH.
This guide walks you through the full developer journey for Remote Workspaces — from registering the external services your task needs to opening a running workspace from your browser or any local client.
Use this guide when you want to run a coding agent in a persistent cloud sandbox instead of on your laptop, and you want to see every step from setting up access through to committing your work back to GitHub.
Before you start
- You need a Kimchi account and access to an organization that has Remote Workspaces enabled.
- Your role must be Owner or Member to create or edit workspace templates and workspaces. Viewer and Analyst roles can view workspaces but cannot create or manage them. See User Roles.
- Registering OAuth apps and MCP servers on the Connections page requires administrator permissions — ask your administrator if you do not have them.
- To connect over SSH instead of the browser-based Web IDE, have any SSH-capable local client available: a plain terminal, local VS Code, or the desktop app or CLI of your coding agent (for example Claude Code or Codex).
Sign in to Kimchi
Sign in to the Kimchi console at app.kimchi.dev with your Kimchi account credentials or your organization's EntraID SSO, if your organization has it configured.
An Owner must have already added you to the Kimchi organization, and optionally to a team, before you can sign in.
Create an OAuth app
An OAuth app lets your workspace sign in to a third-party provider — GitHub, Atlassian, or any OAuth-protected service — as you. An administrator registers the provider once in the console; every member then connects their own account, and workloads act with that user's token, so access always follows each person's own permissions at the provider.
If your organization has already registered the app you need, skip to the next step and just connect your own account: select Connect on the app's row on the OAuth apps tab.
Open the registration form
In the Kimchi console, open Connections and switch to the OAuth apps tab, then select Register OAuth app.
Register the app
Pick a registration method:
- Discover (default) — enter a name and the provider's MCP server URL. If the provider supports automatic registration, Kimchi discovers its OAuth endpoints and creates the app for you, with no client ID or secret to manage.
- Manual — create the OAuth app on the provider's side first, allowing the callback URL shown in the console, then paste the Client ID, Client secret, Authorize URI, and Token URI here.
Connect your account
Select Connect on the registered app and complete the provider's sign-in in the browser. The app shows a Connected status once you are signed in.
For the detailed options — scopes, host patterns, and the header pattern — see Connections (OAuth apps and MCP Gateway).
Create an MCP server
An MCP server connection is registered once for the organization: workloads in your organization's workspaces then reach the external MCP server through the MCP Gateway, which authenticates to the server on the workspace's behalf. There is no per-workspace MCP configuration to maintain. Register it as an organization-level connection and nobody has to configure MCP servers by hand inside a workspace.
The order matters if you plan per-member sign-in: an MCP server connects through an OAuth app, so register the app in the previous step first.
If the MCP server you need is already registered, skip to Store credentials in Remote Credentials.
Open the create form
In the Kimchi console, open Connections and switch to the MCP servers tab, then select Add MCP server.
Name the connection and set the URL
Enter a Name, for example Atlassian MCP, and the MCP server URL — an absolute https:// address, for example https://mcp.example.com/mcp.
Choose how users connect
Pick one of the two authentication models:
- Each member connects individually (OAuth) — recommended. Members sign in with their own accounts; select the OAuth app you registered in the previous step.
- Shared credentials — one credential for everyone using the server: an API key header, a bearer token, HTTP basic auth, or OAuth client credentials.
Create the connection
Select Create connection. The server appears in the MCP servers list and is reachable from workspaces through the gateway.
The authentication type of an MCP server connection cannot be changed later. To use a different type, delete the connection and create it again.
Store credentials in Remote Credentials
For services without an OAuth app connection — to avoid exposing a static token to the agent — store it on the Remote Credentials page. Unlike the organization-level Connections, each member stores their own credentials: they are visible and usable only by you. Everything in your vault is attached automatically to every workspace you create — there is nothing to wire up per workspace.
When a workspace makes an outbound request matching the credential's host pattern, Kimchi injects the credential into the request as it leaves the workspace. The agent never sees the token value, and it cannot be read back from the console.
Open the Remote Credentials page
In the Kimchi console, open Credentials in the Remote Workspaces group, then select Add credential.
Configure the credential
Enter a Name, the Host pattern whose requests receive the credential, and the Injection type — HTTP header, basic auth, query parameter, or environment variable.
Paste the value and create
Paste the credential Value and select Create credential. From then on, matching outbound requests from your workspaces carry the credential automatically.
For host-pattern syntax and injection details, see Remote Credentials.
Pick or create a workspace template
A workspace template defines what a workspace looks like when it starts: which coding agents are preinstalled (Kimchi, Claude Code, Codex), which dependencies and packages are installed, the network egress policy, and an optional setup script.
- If your organization already has a template that fits your task, skip ahead to Create a workspace and select it there.
- If no template fits your task yet, create one yourself. Open the Workspace Templates page, select New template, and configure the coding agents, dependencies, network policy, and setup script your task needs.
Templates you create become available to everyone else in your organization, so check with your team before creating a near-duplicate of an existing one.
Create a workspace
In the Kimchi console sidebar, open the Remote Workspaces page — it lives in the Remote Workspaces group, next to Workspace Templates, Credentials, and Connections. The page lists every workspace you have access to, with its name, creator, status (for example Active or Initializing), and creation date. Each row has an Open in web IDE button and a ⋯ menu for more actions.
Select New workspace
On the Remote Workspaces page, select New workspace.
Choose a template
Pick the workspace template to provision from. The template decides the coding agents, dependencies, network policy, and resources the workspace starts with.
Check your credentials
The create form lists your credential vault as a read-only reminder: every credential stored on the Remote Credentials page is attached to the new workspace automatically. Add anything that is missing with Add credential.
Name the workspace and confirm
Give the workspace a name you will recognize later, then confirm creation.
Kimchi provisions the workspace with everything the template defines — tools, packages, dependencies, network policy, and supported coding agents are ready by the time provisioning completes.
The new workspace appears in the list on the Remote Workspaces page, alongside any other workspaces you or your teammates have created.
Open and use the workspace
Once a workspace is running, open it from any machine — the office desktop, a laptop, a tablet's browser. Both paths below reach the same workspace and the same files.
On the Remote Workspaces page, select Open in web IDE on the workspace's row.
The Web IDE opens a full browser-based editor for the workspace — file explorer, integrated terminals, Git support, and the Kimchi VS Code extension preinstalled. Nothing needs to be installed locally.
Inside the workspace, the coding agent is already authenticated: it connects to the Kimchi gateway with an API key that Kimchi provisions automatically when the workspace is created. This key governs your model access and spending against the budgets your organization has configured — you do not need to paste in a key yourself.
Give the agent a task
Work with the agent the same way you would locally: describe the task, review proposed changes, and let it run tools inside the workspace. Which agent you are talking to — Kimchi, Claude Code, or Codex — depends on which agents the workspace's template installed.
Authenticate to GitHub
The first time the agent (or you) needs to reach a private GitHub repository from the workspace, authenticate with:
gh auth loginThis uses OAuth-based authentication and is the primary way to reach GitHub during this flow. Follow the prompts to complete the browser-based authorization; once authenticated, git and gh operations in the workspace use that session.
If you would rather not run an interactive OAuth flow — or you need a credential injected into requests without ever exposing the token to the agent — use Remote Credentials instead. Store a GitHub token once in the console, and Kimchi injects it into matching outbound requests automatically.
If your organization registered GitHub as an OAuth app in Connections, connect your own account there once — workloads act with your token for the hosts the app covers, and you can skip the in-workspace sign-in.
Disconnect and reconnect later
You can close your browser tab or terminal at any point — the workspace and its running agent session keep going.
To come back later:
- From the console — reopen the Remote Workspaces page and select the workspace to reopen its Web IDE or terminal.
- Over SSH — reconnect using the same SSH details or your local VS Code remote connection.
Reconnecting restores the same agent session, including its output so far, rather than starting a new one.
Inspect, download, and push your work
Once the agent finishes, or whenever you want to check progress:
- Inspect files directly in the Web IDE's file explorer, or with standard shell commands over SSH.
- Download files through the Web IDE, or pull them to your machine over SSH/
scp. - Commit and push changes to GitHub using the credentials you set up in Authenticate to GitHub.
Every workspace and workspace template change — including the ones you just made — is recorded in the Audit Log.
See also
- Remote Workspaces — Workspaces and sessions,
/teleport, and Remote Execution. - Workspace Templates — Define reusable workspace configurations: coding agents, dependencies, network policy, and setup scripts.
- Web IDE — A full browser-based IDE for your Remote Workspace.
- Remote Credentials — Store credentials that remote sessions can use without exposing them to the agent.
- Connections (OAuth apps and MCP Gateway) — Register MCP servers and OAuth apps for the organization, and connect your own account.
- Audit Log — Every change to your workspaces and workspace templates, recorded with who made it and what changed.
- User Roles — Manage who can create and use workspace templates and workspaces.
Updated 5 days ago