Start a Cloud Session From the CLI

A cloud session runs Kiro’s agent in a managed AWS sandbox rather than on your machine. Closing your terminal does not stop the work, and you can reattach from a different computer.

When to use this

Use a cloud session for long-running work you do not want tied to a laptop lid: a large refactor, a spec you will come back to tomorrow, work you start at a desk and check from elsewhere. Stay local when you need Supervised mode, checkpoints, or the local-file context pickers, because cloud sessions do not offer them.

Steps

1. Check the prerequisites. Cloud sessions need CLI v2.17.0 or later, or IDE v1.0.293 or later, and a paid plan. In an organisation, an administrator has to enable them first, because they ship opt-in for enterprises.

2. Start the session with a repository attached:

   kiro-cli --cloud --repo my-org/inventory-service

   You can also start with kiro-cli --cloud and pick the repository with the /repo picker inside the session.

3. Work as normal. The session behaves like a terminal session, but the agent, and the repository it works on, live in the sandbox.

4. Note the session id. You need it to come back.

5. Disconnect whenever you like. The agent keeps going.

6. Reattach from any machine:

   kiro-cli chat --resume-id <id>

7. Use the session dashboard in CLI v2.21.0 to see local and cloud sessions together, rather than tracking ids by hand.

8. Since CLI v2.23.0, V3 cloud sessions can start before you connect a repository. Run /repo afterwards to attach one. This is useful when you want to begin a conversation and decide which repo to work in later.

Check it worked

Start a cloud session, give the agent a task that takes a few minutes, then close the terminal completely. Reopen it and resume with --resume-id. The work should have continued while you were away. That is the entire reason to use a cloud session, so it is the only test that matters.

Common problems

• The flag is not recognised. Update the CLI. Cloud sessions arrived in v2.17.0.
• You are told cloud sessions are unavailable. Your plan is Free, or your organisation has not enabled them. They are opt-in for enterprises.
• You cannot change the branch. The repositories and branch are fixed once the session starts; only Kiro Web offers a branch picker, at creation. Create a new session instead.
• Supervised mode is missing. It is not available in cloud sessions. Work locally if you need turn-by-turn approval.
• You hit a limit. The preview caps you at 10 concurrent sessions. Close finished ones.
• Your personal settings are missing. Project configuration travels with the repository, but your ~/.kiro/ settings stay local unless you sync them through Kiro Web.

Related

• Cloud sessions covers the full preview limits and the enterprise setup.
• Kiro CLI Guide lists the session commands.
• Schedule a Web automation is the unattended version.