This program provides local disk access to the Madoko.net environment. This can be convenient if you do not want to use standard cloud storage (like Dropbox) or are already using a particular Git repository but still want to have the rich editing experience provided by Madoko.net.
It is also useful to render all LaTeX on a local machine.
Ensure you have Node.js installed on your system. When that
is done, you can use the 'node package manager' (
npm) to install
> npm install -g madoko-local
and that's it :-)
Simply run the
madoko-local program with the directory that you would
like to access as an argument. Everything in that directory, and all its
sub-directories will be accessible to Madoko. Here we run it with access
to the current directory:
> madoko-local -r -l . listening on : http://localhost:8080 connecting securely to : https://www.madoko.net serving files under : C:\Users\dknuth\docs running madoko using : madoko (concurrency: 4) --------------------------------------------------------------- access server at : http://localhost#secret=OsuwK3HbMoI7 ---------------------------------------------------------------
This starts a local server that only listens on the local host and does not accept connections from outside. It also shows that it connects using secure https with the Madoko website, and which local directory is accessible within Madoko.
-r flag also runs Madoko on the local machine to render math or PDF
using LaTeX (without
-r this is done on the madoko.net server which
may be slower).
-l flag will launch the browser and go to the listed url, i.e.
http://localhost:8080#secret=OsuwK3HbMoI7 in our example. The 'secret' in
the url is unique on each computer and used as an extra level of
The url will directly open up the standard Madoko website and all
features are usable as normal, including cooperation with multiple
authors through cloud storage like Dropbox. However, in the
you can now also open files from your local disk and edit them as usual.
** Note.** With Internet Explorer, you will be unable to log into remote
services (like Onedrive) under the localhost. If you use another browser
or just access the local disk this is no problem of course. Otherwise,
you must add
https://www.madoko.net to both the trusted websites (under
the security tab), and to the websites that can always add cookies
(under the privacy tab).
Command line options
> madoko-local [options] [mount-directory]
mount-directory: The server only provides access to files and subdirectories under the mount directory but not outside of it. If not given, the last specified directory is used (which is stored in the local configuration file). If this is the first run the current working directory is used.
--help: Show help on the command line options.
--version: Show the current version of the program.
--launch: After starting the local server, launch the default browser at the correct localhost address.
--run, : Run Madoko locally to generate PDF's, render mathematics and to generate bibliographies. This means you are no longer dependent on the server to run LaTeX for you. This flag requires that you have installed both Madoko (
npm install -g madoko) and LaTeX -- it is recommended to use the latest TexLive simple (or full) installation which is also used on the Madoko server.
--verbose[=<n>]: Emit more tracing messages. Set
nto 2 to be the most verbose.
--secret[=secret]: If no secret is provided, a new random secret is generated. Otherwise, the provided secret is used. A secret is usually stored in the configuration file such that you have a stable url for Madoko. Using the
--secretflag you can generate a new secret every once in a while.
--homedir=<dir>: Specify the user home directory. In this directory
madoko-localwill create a
.madokodirectory that contains log files and the local configuration file (
--concurrency=<n>: Run madoko with the specified concurrency to speed up svg rendering for mathematics.
--origin=<url>: Instead of serving
https://www.madoko.netuse the specified
url. Only specify trusted websites here since that website can obtain local disk access!
--port=<n>: Use the specified port to serve
madoko-local. This can be useful if you have other servers running that already use port 8080.
--rundir=<dir>, : The directory under which Madoko stores temporary files when running Madoko (if the
--runflag is present). Defaults to
--runcmd=<cmd>, : The command to use when running Madoko locally. By default this is
--runflags=<flags>, : Extra flags to pass to the Madoko program when running locally. These flags are appended to the standard flags, namely:
-vv -mmath-embed:512 --odir=out --sandbox.
madoko-local stores the last generated secret and last used
mount-directory in the local configuration file at
Running LaTeX locally
When you pass the
--run flag, the
madoko-local program will not
only serve files, but also run the local Madoko installation to generate
PDF's, render mathematics, or generate the bibliography. This means that
the Madoko web server is only used for the editing environment and updates
-- all document processing will be done locally.
When running locally,
madoko-local will store
files temporarily under the
<rundir>/<temp-name> directory where it runs
Madoko with the
--sandbox flag to restrict access to files under that
When running Madoko locally, you need to have both Madoko and LaTeX installed. Madoko can be installed through the Node package manager as:
> npm install -g madoko
For LaTeX, the latest TexLive full installation is recommended since it
is also used on the Madoko server and it respects the
openout_any settings which are needed to run LaTeX safely in a sandboxed mode.
Also, for rendering of mathematics, you need to ensure you have
dvisvgm version 1.14 or higher installed. Instructions on how to
dvisvgm can be found in the reference manual.
The server is designed with multiple security layers:
- The server only listens on the localhost itself and does not accept
outside connections. All files are only sent and received inside the
localhost (and even the
madoko.netserver cannot connect directly to
specified origin (
- The above is already enough if using a secure browser that prevents cross-site scripting requests, but as an extra security layer, the server is started with a particular secret and only accepts requests that match the secret.
- The server only gives access to files and directories under the specified mount directory.
- When running Madoko locally, it runs it also in a sandbox restricting access to files and directories under a specific run directory.