Shares & Custom Domains

Shares expose ports from a running VM to the internet. If you used instavm deploy, the CLI already created a share for you. Use the commands below when you want to manage one manually.

Create a share

CLI

instavm share create vm_abc123 3000 --public

Python

from instavm import InstaVM

client = InstaVM("your_api_key")

share = client.shares.create(
    vm_id="vm_abc123",
    port=3000,
    is_public=True,
)

print(f"URL: {share.get('url')}")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const share = await client.shares.create({
  vm_id: 'vm_abc123',
  port: 3000,
  is_public: true,
});

console.log(`URL: ${share.url}`);

Public vs private shares

• Public shares are accessible by anyone with the URL.
• Private shares require an access token or a later visibility change.

CLI

# Private share (default, no --public flag)
instavm share create vm_abc123 3000

Python

share = client.shares.create(vm_id="vm_abc123", port=3000, is_public=False)
print(f"Access token: {share.get('access_token')}")

JavaScript

const share = await client.shares.create({
  vm_id: 'vm_abc123',
  port: 3000,
  is_public: false,
});

console.log(`Access token: ${share.access_token}`);

Update or revoke a share

CLI

instavm share set-public share_def456
instavm share set-private share_def456
instavm share revoke share_def456

Python

client.shares.update(share_id="share_def456", is_public=True)
client.shares.update(share_id="share_def456", revoke=True)

JavaScript

await client.shares.update('share_def456', { is_public: true });
await client.shares.update('share_def456', { revoke: true });

Custom domains

Point your own domain at a shared port for production-ready URLs.

Create a custom domain

curl -X POST https://api.instavm.io/v1/custom-domains \
  -H "X-API-Key: instavm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.example.com", "share_id": "share_def456"}'

Verify DNS

Add a CNAME record pointing your domain to the provided target, then verify:

curl -X POST https://api.instavm.io/v1/custom-domains/{domain_id}/verify \
  -H "X-API-Key: instavm_sk_..."

List and delete

curl https://api.instavm.io/v1/custom-domains \
  -H "X-API-Key: instavm_sk_..."

curl -X DELETE https://api.instavm.io/v1/custom-domains/{domain_id} \
  -H "X-API-Key: instavm_sk_..."

Use case: preview a web app

The easiest preview path is Deploy a Web App with instavm deploy. If you are working directly with the SDK, you can create the share yourself:

CLI

# The fastest path — deploys, creates VM, and shares in one step
instavm deploy --port 8080

Python

from instavm import InstaVM

with InstaVM("your_api_key") as vm:
    vm.execute("""
import subprocess, sys
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'flask'])
    """)

    vm.execute_async("""
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return '<h1>Hello from InstaVM</h1>'

app.run(host='0.0.0.0', port=8080)
    """)

    share = vm.shares.create(port=8080, is_public=True)
    print(f"Preview: {share.get('url')}")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

await client.execute(`
import subprocess, sys
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'flask'])
`);

await client.executeAsync(`
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return '<h1>Hello from InstaVM</h1>'

app.run(host='0.0.0.0', port=8080)
`);

const share = await client.shares.create({ port: 8080, is_public: true });
console.log(`Preview: ${share.url}`);

await client.dispose();

Next steps

• Deploy a Web App -- CLI-first deployment walkthrough
• REST API: Shares -- API endpoints