Client Sessions

Freestyle VMs can be securely controlled from the client with access tokens.

Setting up the identity + access token

To set up the access token for your VM, you create or use an existing identity, grant it access to the VM, and get a token.

Then you send the token to your client.

import { freestyle } from "freestyle-sandboxes";

const { id, vm } = await freestyle.vms.create({});
const { identity } = await freestyle.identities.create()

await identity.permissions.vms.grant({
  vmId: id,
})

const { token } = await identity.tokens.create();

return token

Then, on the client side, you construct an instance of the Freestyle SDK with the token

import { Freestyle } from "freestyle-sandboxes";

const freestyle = new Freestyle({
    accessToken: token
})

You've now constructed an instance of the client that only has the permissions you've explicitly granted — in this case the right to run read and write operations on this VM as any user.

Acting as a Linux user

When you perform operations on the VM, by default you act as the root user.

You can set the user for operations by using the user method. This returns a new instance of the VM client scoped to that user.

const { vm } = await freestyle.vms.create({
  users: [
    {
      name: "alice",
    },
    {
      name: "bob",
    },
  ],
});

const aliceVm = vm.user({username: 'alice'})
const bobVm = vm.user({username: 'bob'});

const aliceFiles = await aliceVm.fs.readDir('/');
const bobFiles = await bobVm.fs.readDir('/');

the .user method does not check if the identity has permission to access that user or if that user exists.

Limitations

Client Sessions are limited to operations on existing VMs, they cannot be used to create new VMs. This is an intentional pattern to protect you from users creating resources without your intention. We envision them being used for the ongoing operations of an agent in a sandbox ie running code, listing files, and operating within a VM. A client token does have the ability to wake a sleeping VM.