Domain Tools

Search, register, and manage DNS records for domains via Conway

Domain tools enable agents to autonomously acquire and configure internet domains for hosting services, APIs, and public presence.

Domain Search

search_domains

Search for available domain names and get pricing.

query · string · required

Domain name or keyword (e.g., ‘mysite’ or ‘mysite.com’)

tlds · string

Comma-separated TLDs to check (e.g., ‘com,io,ai’)

Default: com,io,ai,xyz,net,org,dev

Risk Level: safe

Returns: List of domains with availability and pricing

Search Keyword

await search_domains({ query: 'myagent' });
// Returns:
// myagent.com: AVAILABLE ($12.00/yr)
// myagent.io: AVAILABLE ($35.00/yr)
// myagent.ai: AVAILABLE ($80.00/yr)
// myagent.xyz: AVAILABLE ($8.00/yr)
// myagent.net: taken
// myagent.org: AVAILABLE ($15.00/yr)
// myagent.dev: AVAILABLE ($12.00/yr)

Use broad TLD searches to find affordable options. .xyz and .dev are typically cheaper than .com or .ai.

Domain Registration

register_domain

Register a domain name using USDC via x402 payment.

domain · string · required

Full domain to register (e.g., ‘mysite.com’)

years · number · default: 1

Registration period in years (1-10)

Risk Level: dangerous

Returns: Registration confirmation with expiration and transaction ID

Example

await register_domain({
  domain: 'myagent.xyz',
  years: 2
});
// Returns: "Domain registered: myagent.xyz (status: active, expires: 2026-01-15, tx: tx_abc123)"

Payment & Preflight

Domain registration:

1. Checks USDC balance before attempting
2. Verifies domain availability
3. Initiates x402 payment to registrar
4. Returns error if insufficient funds or domain taken

Annual Renewal

Domains must be renewed annually. Set up a heartbeat reminder:

await modify_heartbeat({
  action: 'add',
  name: 'domain_renewal_check',
  schedule: '0 0 1 * *', // Monthly
  task: 'check_domain_expiration'
});

DNS Management

manage_dns

Manage DNS records for a domain you own.

action · string · required

Action: list, add, or delete

domain · string · required

Domain name (e.g., ‘mysite.com’)

type · string

Record type for add: A, AAAA, CNAME, MX, TXT, SRV

host · string

Record host for add (e.g., @ for root, www, api)

value · string

Record value for add (IP address, target domain, etc.)

ttl · number · default: 3600

TTL in seconds for add

record_id · string

Record ID for delete (from list output)

Risk Level: safe

Returns: Record list, add confirmation, or delete confirmation

List Records

await manage_dns({
  action: 'list',
  domain: 'myagent.xyz'
});
// Returns:
// [rec_001] A @ -> 1.2.3.4 (TTL: 3600)
// [rec_002] CNAME www -> myagent.xyz (TTL: 3600)
// [rec_003] TXT @ -> "v=spf1 include:_spf.conway.run ~all" (TTL: 3600)

DNS changes may take 5-60 minutes to propagate globally. Use low TTL (300-600s) for records you plan to update frequently.

Common Workflows

Register and Configure Domain

// 1. Search for available domains
const results = await search_domains({
  query: 'myagent',
  tlds: 'xyz,dev,com'
});

if (results.includes('myagent.xyz: AVAILABLE')) {
  // 2. Register domain
  await register_domain({
    domain: 'myagent.xyz',
    years: 1
  });
  
  // 3. Get public URL from exposed port
  const portInfo = await expose_port({ port: 3000 });
  // Extract IP or use Conway public URL
  
  // 4. Point domain to service
  await manage_dns({
    action: 'add',
    domain: 'myagent.xyz',
    type: 'CNAME',
    host: '@',
    value: 'abc123.conway.run' // From expose_port
  });
  
  console.log('Domain configured: https://myagent.xyz');
}

Host API Service

// 1. Start API server
await write_file({
  path: '/app/server.js',
  content: `
const express = require('express');
const app = express();
app.get('/api/status', (req, res) => {
  res.json({ status: 'alive', timestamp: Date.now() });
});
app.listen(8080);
`
});

await exec({ command: 'node /app/server.js &' });

// 2. Expose port
await expose_port({ port: 8080 });

// 3. Configure DNS
await manage_dns({
  action: 'add',
  domain: 'myagent.xyz',
  type: 'CNAME',
  host: 'api',
  value: 'abc123.conway.run'
});

console.log('API available at: https://api.myagent.xyz/api/status');

Email Configuration (MX Records)

// Add MX records for email
await manage_dns({
  action: 'add',
  domain: 'myagent.xyz',
  type: 'MX',
  host: '@',
  value: '10 mail.conway.run' // Priority 10
});

await manage_dns({
  action: 'add',
  domain: 'myagent.xyz',
  type: 'MX',
  host: '@',
  value: '20 mail2.conway.run' // Backup priority 20
});

// Add SPF record
await manage_dns({
  action: 'add',
  domain: 'myagent.xyz',
  type: 'TXT',
  host: '@',
  value: 'v=spf1 include:_spf.conway.run ~all'
});

Subdomain Management

// Add subdomains for different services
const services = [
  { host: 'api', target: 'api.conway.run' },
  { host: 'docs', target: 'docs.conway.run' },
  { host: 'status', target: 'status.conway.run' }
];

for (const svc of services) {
  await manage_dns({
    action: 'add',
    domain: 'myagent.xyz',
    type: 'CNAME',
    host: svc.host,
    value: svc.target
  });
}

Domain Monitoring

// Check all DNS records
const records = await manage_dns({
  action: 'list',
  domain: 'myagent.xyz'
});

// Verify critical records exist
if (!records.includes('A @')) {
  console.log('WARNING: No root A record');
}

if (!records.includes('CNAME www')) {
  console.log('INFO: No www subdomain configured');
}

DNS Record Types

A Record

Points domain to IPv4 address.

{ type: 'A', host: '@', value: '1.2.3.4' }

AAAA Record

Points domain to IPv6 address.

{ type: 'AAAA', host: '@', value: '2001:db8::1' }

CNAME Record

Alias to another domain.

{ type: 'CNAME', host: 'www', value: 'example.com' }

MX Record

Mail server for domain. Value includes priority.

{ type: 'MX', host: '@', value: '10 mail.example.com' }

TXT Record

Arbitrary text, often for verification or SPF.

{ type: 'TXT', host: '@', value: 'v=spf1 include:_spf.google.com ~all' }

SRV Record

Service location record.

{ type: 'SRV', host: '_service._tcp', value: '10 60 5060 service.example.com' }

Domain Pricing

Typical annual registration costs:

TLD	Price/yr	Best For
.xyz	$8-12	Cheap, flexible
.dev	$12-15	Developer tools
.com	$12-15	Professional presence
.net	$12-18	Networks, infrastructure
.org	$15-20	Open source, communities
.io	$35-40	Tech startups
.ai	$60-80	AI/ML agents

Use .xyz or .dev for cost-effective agent domains. Reserve .ai for premium branding.

Error Handling

// Domain not available
const result = await register_domain({ domain: 'google.com' });
if (result.includes('not available')) {
  console.log('Domain already registered');
}

// Insufficient funds
try {
  await register_domain({ domain: 'myagent.xyz' });
} catch (err) {
  if (err.includes('Insufficient USDC')) {
    const balance = await check_usdc_balance({});
    console.log('Need more USDC:', balance);
  }
}

// DNS record not found
const deleteResult = await manage_dns({
  action: 'delete',
  domain: 'myagent.xyz',
  record_id: 'invalid_id'
});
if (deleteResult.includes('not found')) {
  // List records to find correct ID
  await manage_dns({ action: 'list', domain: 'myagent.xyz' });
}

Best Practices

Use short TTLs during setup

Set TTL to 300-600s when configuring. Increase to 3600+ once stable.

Always configure www subdomain

Point www to root with CNAME for consistency.

Enable HTTPS

Conway automatically provisions SSL certificates for exposed ports.

Monitor expiration

Set up heartbeat reminders for renewal 30 days before expiration.

Keep DNS records minimal

Only create records you actively use. Remove unused records promptly.

Related

VM Tools

Expose ports for web services

Financial Tools

USDC payments and x402

x402 Protocol

Automated USDC payments

Conway Domains

Domain management overview