feat: add sessions api documentation (#278)

* Ives' commit

* copy improvements

* chore: add some more docs

---------

Co-authored-by: Filipe Lima <[email protected]>

Author: CompuIves

packages/projects-docs/pages/sdk/_meta.json

@@ -17,6 +17,7 @@
   "shells": "Shells",
   "ports": "Ports & Previews",
   "tasks": "Tasks & Setup",
+  "sessions": "Sessions",
   "specs": "VM Specs",
 
   "-- resources": {

packages/projects-docs/pages/sdk/sessions.mdx

@@ -0,0 +1,76 @@
+---
+title: Sessions
+description: Sessions allow you to create multiple users inside a single sandbox.
+---
+
+import { Callout } from 'nextra-theme-docs'
+
+# Sessions
+
+Normally, when you create a sandbox, we create a single user (called `pitcher-host`) inside the sandbox, which you can use to interact with it. This user has write access to any API. We refer to this session as the "global" session.
+
+```ts
+const sandbox = await sdk.sandbox.create();
+
+// Now I have a session where I act as `pitcher-host` user.
+// Any action I do will be done as `pitcher-host` user.
+await sandbox.fs.writeTextFile('test.txt', 'Hello World');
+```
+
+<Callout>
+When you run `whoami`, it will say you're `root`. That's because we run every session inside a Docker container where you are `root`. The container itself, however, is started as the user of your session.
+</Callout>
+
+Now, let's say you want another user to connect with the sandbox as well but don't want them to act on behalf of your global session. Perhaps you want them to have different permissions, or you want to isolate their actions from the global session. In that case, you can create a new session.
+
+```ts
+const sandbox = await sdk.sandbox.create();
+
+// Now create a new session that only has read access to the sandbox.
+const session = await sandbox.sessions.createReadOnly();
+
+// I have access to the normal sandbox api, but I only have read access
+// This means I cannot write files or open shells, but I _can_ read them
+await session.fs.writeTextFile('test.txt', 'Hello World'); // This will throw an error.
+await session.fs.readTextFile('test.txt'); // This will work.
+
+// I can also create sessions with write access
+const session2 = await sandbox.sessions.create('my-session-id', {
+  permission: 'write',
+});
+await session2.fs.writeTextFile('test.ext', 'Hello World'); // This will work
+```
+
+If you create a session with the same id as before (e.g., `my-session-id`), we will reuse the existing session.
+
+## Sessions Inside the Browser
+
+By default, we will automatically connect to the session when calling `sandbox.sessions.create()`. However, if you want to connect from the browser, you can instead create a session on the server and share a token to the browser, which the browser can then use to connect. Here is an example:
+
+```ts
+const sandbox = await sdk.sandbox.create();
+
+const sessionInfo = sandbox.sessions.create('my-new-session', { permission: 'write', autoConnect: false });
+
+// Now pass sessionInfo to the browser, and inside the browser do:
+
+import { connectToSandbox } from '@codesandbox/sdk/browser';
+
+const session = await connectToSandbox(sessionInfo);
+```
+
+## Storage
+
+Every session will have the same filesystem as the global session. This means that if one user creates a file inside the workspace folder (or even the home folder) other users will be able to see it. There is one exception to this the `~/.private` folder will be private for each session. No other session (including the global session) will be able to read or write to files inside this folder.
+
+## Use Cases
+
+You can use this API for multiple use cases:
+
+### Shared Branches / Sandboxes
+
+When building a collaborative code editor, you can allow multiple users to connect to the same branch and collaboratively edit files without the ability to affect each other. Every user can have their own secrets (like git token) stored in `~/.private` so they can commit and pull with their own credentials without sharing those credentials with others.
+
+### Anonymous Previews
+
+If you want to share a sandbox with someone else, and give them access to reading files & shells, you can create a read-only session when they connect to the sandbox. This way they can see what's running, and how it works, but they cannot change the code. If they want to make changes, you can call `sandbox.fork()` to create a copy and give them access to a write session there.