content/getting-started/cli.md · urbit.org

git.iko.soy/urbit.org

on d8d22ee help sign in

urbit.org/content/getting-started/cli.md

269 lines 8.9 kB history raw

1+++

2title = "Command line app"

3weight = 2

4description = "Installation instructions for power users."

5+++

7If you're a power user, you can run the Urbit virtual machine directly using the

8command line. This can be run on your local machine or a server in the cloud, we

9just cover the general case here.

11Note there is a much more comprehensive [cloud hosting

12guide](https://operators.urbit.org/manual/running/hosting) which walks through

13setting up Urbit on a [Digital Ocean](https://www.digitalocean.com/) VPS.

15### 1. System Requirements {% #about-swap-space %}

17- **Processor**: 1 core

18- **Memory**: 2GB

19- **Storage**: At least a few GB, 40-50GB preferable

20- **Network**: Any

22**A note on memory**: By default, the Urbit runtime needs 2GB of free memory,

23and will fail to boot without it. Urbit usually only uses a portion of this, so

24it's possible to use a swap file to makeup for a shortfall without degrading

25performance. For instructions on how to configure a swap file on Linux, see

26[this linuxize.com guide](https://linuxize.com/post/create-a-linux-swap-file/).

28**A note on storage**: Urbit saves every event it processes to its [Event

29Log](https://developers.urbit.org/reference/glossary/eventlog). This means its

30disk usage slowly grows over time. Until event log truncation is implemented,

31it's advisable to have 40 or 50GB of disk space available, so you don't have to

32worry about running out for a long time. If you don't have that much, your ship

33will still run fine, but you may run out of space some months down the line.

35### 2. Install Urbit

37Choose your operating system and run the given command in your terminal to

38download the Urbit runtime:

40{% tabs %}

42{% tab label="MacOS" %}

44```bash

45curl -L https://urbit.org/install/mac/latest | tar xzk --strip=1 && ./urbit

46```

48> Note our Mac build is only compatible with Apple Silicon (M1/M2) via Rosetta.

49> If you have such a machine you may need to run the following command:

50>

51> ```

52> /usr/sbin/softwareupdate --install-rosetta --agree-to-license

53> ```

55{% /tab %}

57{% tab label="Linux" %}

59```shell

60curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 && ./urbit

61```

63> Linux users may need to run this command in another terminal window to access

64> your urbit on port 80:

65>

66> ```shell

67> sudo apt-get install libcap2-bin

68> sudo setcap 'cap_net_bind_service=+ep' ./urbit

69> ```

71{% /tab %}

73{% tab label="Linux ARM64" %}

75Note this is for the AArch64 architecture.

77```shell

78curl -L https://urbit.org/install/linux-aarch64/latest | tar xzk --strip=1 && ./urbit

79```

81> Linux users may need to run this command in another terminal window to access

82> your urbit on port 80:

83>

84> ```shell

85> sudo apt-get install libcap2-bin

86> sudo setcap 'cap_net_bind_service=+ep' ./urbit

87> ```

89{% /tab %}

91{% tab label="Windows" %}

93```winbatch

94curl -L https://urbit.org/install/windows/latest | tar -xzkf - --strip-components=1 && urbit

95```

97> Windows 10 build 17063 and later includes the familiar `curl` and `tar`

98> command-line tools. If you're running an older version of Windows, you may need

99> to visit

100> [https://github.com/urbit/urbit/releases/latest](https://github.com/urbit/urbit/releases/latest)

101> in the browser, download the `windows.zip` file, extract it and execute the

102> contained `urbit.exe` file in the command prompt.

103

104{% /tab %}

105

106{% /tabs %}

107

108If successful, you will see a block of output beginning with the line:

109

110```

111Urbit: a personal server operating function

112```

113

114### 3. Boot Urbit

115

116An Urbit instance is intrinsically tied to a unique identity called an **Urbit

117ID**. There are five classes of Urbit ID, but we will consider two here: comets

118and planets.

119

120- **Comet:** A comet is an identity which anyone can generate themselves, for

121 free. It's a good option to try out Urbit. Comets are limited by the fact they

122 cannot be "factory reset", meaning if your urbit somehow becomes broken or

123 corrupted then you'll have to start again with a new identity. In that sense,

124 they are impermanent.

125

126- **Planet:** A planet is a permanent identity which you own forever. Planets

127 are the class intended for individuals. While there are essentially an

128 unlimited number of comets, planets are more scarce (preventing spamming,

129 among other things). This scarcity means they usually aren't free (though

130 sometimes nice people give them away). This guide will assume you've already

131 acquired a planet. If you haven't, you can refer to the ["Get a planet"

132 guide](https://urbit.org/getting-started/get-planet) before continuing.

133

134Follow the instructions for your case:

135

136{% tabs %}

137

138{% tab label="Boot a Comet" %}

139

140In the terminal, with the `urbit` binary you installed in the previous step, a

141comet can be booted with the `-c` option:

142

143```bash

144./urbit -c mycomet

145```

146

147> `mycomet` will be the name given to the data folder it will create. You can

148> choose any name you like.

149

150It may take a while to initialize the comet (usually only a couple of minutes,

151but it could take longer). When it's done, it'll take you to the dojo prompt

152(the dojo is Urbit's shell):

153

154```

155ames: live on 31337

156http: web interface live on http://localhost:8080

157http: loopback live on http://localhost:12321

158~sampel_marzod:dojo>

159```

160

161You can shut down the comet again by typing `|exit` in the dojo or hitting

162`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

163folder, so you can start it up again by doing:

164

165```bash

166./mycomet/.run

167```

168

169Since comets are often used temporarily and then discarded, kernel updates are

170not enabled by default. If you plan to use your comet for a while, it's a good

171idea to enable updates with the following command in the dojo:

172

173```

174|ota (sein:title our now our)

175```

176

177Lastly, while the dojo is quite powerful, most people use their urbit via

178Landscape, the browser-based UI. In order to access Landscape, you need your web

179login code. You can get this by running the following command in the dojo:

180

181```

182+code

183```

184

185It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.

186Copy the code it gives you to the clipboard.

187

188{% /tab %}

189

190{% tab label="Boot a Planet" %}

191

192In order to boot a planet, you need a copy of its private keys. If you got your

193planet via a claim link, the passport backup `.zip` file you downloaded will

194contain a file called something like `sampel-palnet-1.key`. If you don't have

195the passport backup or you got your planet by another method, you can instead

196login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS

197section, and hit the "Download Keyfile" button.

198

199Back in the terminal, with the `urbit` binary you installed in the previous

200step, you can boot your planet with the following command (replacing

201`sampel-palnet` with your own planet and pointing to the location of your

202keyfile):

203

204```bash

205./urbit -w sampel-palnet -k sampel-palnet-1.key

206```

207

208This will create a data folder with the name of your planet and begin booting.

209It may take a while to initialize the planet (usually only a couple of minutes,

210but it could take longer). When it's done, it'll take you to the dojo prompt

211(the dojo is Urbit's shell):

212

213```

214ames: live on 31337

215http: web interface live on http://localhost:8080

216http: loopback live on http://localhost:12321

217~sampel-palnet:dojo>

218```

219

220You can shut down the planet again by typing `|exit` in the dojo or hitting

221`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

222folder, so you can start it up again by doing:

223

224```bash

225./sampel-palnet/.run

226```

227

228While the dojo is quite powerful, most people use their urbit via Landscape, the

229browser-based UI. In order to access Landscape, you need your web login code.

230You can get this by running the following command in the dojo:

231

232```

233+code

234```

235

236It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`

237(note this is a separate code to your master ticket). Copy the code it gives you

238to the clipboard.

239

240One last thing: The `sampel-palnet-1.key` keyfile is only needed once, when you

241first boot your planet. Now that it's booted, it's good security practice to

242delete that keyfile.

244{% /tab %}

246{% /tabs %}

248### 4. Login

250While your urbit is running, the web interface called *Landscape* can be

251accessed in the browser. Its URL will usually be either `localhost` or

252`localhost:8080`, depending on your platform. To check the address, you can look

253at the boot messages in the terminal. You should see a line like:

254

255```

256http: web interface live on http://localhost:8080

257```

258

259Whichever address and port it says there is the one to open in the browser.

260

261Once open, you'll be presented with the login screen. Paste in the web login

262code you copied from the dojo in the previous step and hit "continue". You'll

263now be taken to your homescreen, with tiles for the default apps such as Groups

264and Terminal.

265

266### Next steps

267

268Learn how to [get around your

269urbit](https://urbit.org/getting-started/getting-around).